Versioning Scheme

This project uses semantic versioning. Given a version number MAJOR.MINOR.PATCH, we increment the

  1. MAJOR version when we make incompatible API changes,

  2. MINOR version when we add functionality in a backwards-compatible manner, and

  3. PATCH version when we make backwards-compatible bug fixes.

Additionally, pre-release, post-release and developmental release specifiers can be appended.


As long as the MAJOR number is 0 (i.e. the API has not stabilized), even MINOR increases may introduce incompatible API changes.

Publishing a New Release


New versions can only be released by project maintainers that have write access to the upstream repository.

Follow these steps when publishing a new release.

1. Update the Version Number

Create a new branch out of main named chore/release/vMAJOR.MINOR.PATCH.

git checkout main
git checkout -b chore/release/vMAJOR.MINOR.PATCH

Update AUTHORS.rst to list all authors that have contributed to the new release and commit the changes to the new branch.

Add authors that have contributed for the first time to the list of authors in the pyproject.toml file and commit the changes to the new branch.

Update the version number in pyproject.toml to the new MAJOR.MINOR.PATCH version and commit the changes to the new branch.

Push the branch to the upstream repository.

git push --set-upstream origin chore/release/vMAJOR.MINOR.PATCH

Open the upstream repository in GitHub, create a pull request and merge the branch into main when all tests passed successfully.

Pull the changes to your remote repository.

git checkout main
git pull

1. Create a New Tag

On the main branch, create a new tag that contains the new MAJOR.MINOR.PATCH version number prefixed with a “v”:

git checkout main

As tag message enter:


Release notes at

Push the tag to the upstream repository.


First push, then push --tags!

git push
git push --tags

3. Create a New Release

Open the upstream repository in GitHub and follow the steps outlined in the GitHub doc page Creating automatically generated release notes for a new release. When selecting a tag, use the tag you just created in the previous step. Carefully check the automatically generated release notes and make changes if necessary.