Developer Documentation

Installing Development Dependencies

Poetry installs dev dependencies by default from the poetry.lock or pyproject.toml files. Just run

poetry install

Testing

Testing is run with pytest and the order is randomized by pytest-randomly. To run all tests, run

pytest tests

To run all tests in docker containers (tests against many versions of python), run

docker-compose up --build && docker-compose down

Making a Pull Request

Feel free to fork this repo and submit a PR!

  • If you are working on an issue, link your PR to that issue.

  • All PRs should be destined for the main branch (trunk-based development).

  • Reviews are required before merging and our automated tests must pass.

  • Please fill out the PR template that is populated when creating a PR in the GitHub interface.

Release Process

Reference: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow

  1. Create a release candidate branch named according to the version to be released. This branch is used to polish the release but is fundamentally not different from any other feature branch in trunk-based development. The naming convention is release/X.Y.Z.

  2. Bump the version of the package to the version you are about to release, either manually by editing pyproject.toml or by running poetry version X.Y.Z or bumping according to a valid bump rule like poetry version minor (see poetry docs: https://python-poetry.org/docs/cli/#version).

  3. Update the version identifier in CITATION.cff.

  4. Update changelog.md to reflect that the version is now “released” and revisit README.md to keep it up to date.

  5. Open a PR to merge the release branch into main. This informs the rest of the team how the release process is progressing as you polish the release branch. You may need to rebase the release branch onto any recent changes to main and resolve any conflicts on a regular basis.

  6. When you are satisfied that the release branch is ready, merge the PR into main.

  7. Check out the main branch, pull the merged changes, and tag the newly created merge commit with the desired version X.Y.Z and push the tag upstream.

    git tag -a X.Y.Z -m "version release X.Y.Z"
git push origin X.Y.Z

  8. Ensure that you have main checked out and build the package (see below). Check that the version of the built artifacts is as you expect (should match the version git tag and the output from poetry version --short).

  9. Optionally distribute the artifacts to PyPI/Nexus if desired (see below).

Building and Distribution

  1. Ensure that poetry is installed by running poetry --version.

  2. To build the distribution archives, run poetry build.

  3. To upload the wheel to Nexus, run poetry publish. You will need credentials to sign in to PyPI.