Poliosim overview

The repo is organized as follows:

  • Poliosim, in the folder poliosim, is a standalone Python library for performing polio simulations.

  • Scripts that use Poliosim to run analyses are in the scripts, examples, and pipeline folder.

  • Poliosim tests are in the tests folder.

Installation

Run pip install -e . to install Poliosim and its required dependencies. This will make poliosim available on the Python path.

Usage

You can run a simple example with tests/test_simple.py. For more advanced usage, see the scripts folders listed above, e.g. pipeline/example_drone.py.

Documentation

Documentation is available at https://docs.idmod.org/projects/poliosim/en/latest/.

Contributing

Before starting

  • Everything you’re working on must be linked to an issue. If you notice that something needs to be done (even small things or things nearly finished) and there isn’t an issue for it, create an issue. This helps track who is doing what and why.

  • ALL PRs should be linked to at least one issue. If you find yourself working on a PR and there’s no issue associated with it, please check with the project owner before proceeding.

  • All PRs will be assigned to the project owner for review automatically, and typically you would also assign to at least one other person for review, depending on relevance.

  • At times there may be a backlog of issues, but there should never be a big backlog of PRs. (If you’re unsure whether to make a PR, write a detailed issue first.)

    • What if there are two people working on PRs at the same time?

      • Take a look at the issue priority. The PR addressing the higher priority issue should merge first. Make sure you pull the new master after that merge before you push changes for your PR. If both issues are high priority, the one with more time-sensitive commits should be merged first. If you’re unsure, ask.

  • If we do have a backlog of PRs, it’s fine to make a new branch off your current PR, and make a new PR from that. These “cumulative” PRs are not ideal, but they are better than creating merge conflicts with yourself!

  • High priority issues are organized in the “Project” view from top (most urgent) to bottom (least urgent) and may be labeled with highpriority as appropriate. If you are working on something that is urgent or blocks other development, please set a reasonable deadline for review (can be updated, of course!).

  • Keep PRs as small as possible: e.g., one issue, one PR. Small PRs are easier to review and merge.

  • Before starting work, always ensure you’ve pulled from master. If you spend more than a few days on your PR, make sure you pull from master regularly. Before making a PR, ensure that your branch is up to date with master.

  • Even if your work isn’t ready for a PR, push it regularly. A guiding principle is to commit locally every few minutes and push to your branch every 1-2 hours.

  • Do not force-push a branch. If you can’t push normally, it usually means you need to pull first.

Pull request checklist

  1. Make sure tests pass on your PR, and that any new features are covered by tests. If tests don’t pass, mark the PR as draft until they do.

  2. Make sure you’ve updated version.py.

  3. Make sure you’ve updated the changelog.

  4. Do not “squash and merge” pull requests (create a merge commit instead).