Contributing
Setting up the development environment
The easiest way to setup your development environment and install the needed dependendecies is to use Poetry. For instructions, see Poetry Docs - Installation.
After installing Poetry you can use the following command to install all the needed dependencies:
poetry install
After installing the dependencies, you can enter the Python virtual environment that Poetry created with the following command:
poetry shell
Running tests and linters
Tests and code linters are executed in CI pipeline when you open a new pull request, but you can also execute them locally. This project contains a Makefile that allows you to easily run all tests and linters with one command:
# Run tests and linters
make
# Run only tests
make test
# Run only linters
make lint
Running tests with multiple Python versions using Tox
CI pipeline also runs tests using all the supported Python versions. You can use Tox if you want to run these tests yourself, but first you need to have all different Python versions available in your local system.
One option is to use Pyenv to manage different Python versions. For example, if you would want to run the test suite using Python versions 3.12 and 3.13, you can install the needed Python versions with the following commands:
pyenv install 3.12
pyenv install 3.13
After the installation, you can make the installed Python versions available globally:
pyenv global 3.12 3.13
Finally, you can run Tox and it should discover the installed Python version automatically:
tox -e py312,py313
You can omit the -e argument if you want to run the tests against all supported Python versions. If everything works, the output should be something similar to this:
...
__________ summary __________
py312: commands succeeded
py313: commands succeeded
congratulations :)
Updating documentation
The documentation is built using Mkdocs. After installing the development dependencies, you can simply run the following command to serve the documentation on your local machine:
mkdocs serve
For more details, see Mkdocs - User guide and Mkdocs Material theme documentation.
The documentation is automatically deployed to Read the Docs service on every new commit to the default branch.
Releasing a new version
Releases are made with scripts/release.py. It needs GitHub CLI
and a clean, up-to-date master branch.
- Bump the version in
pyproject.tomlandsetup.py, move the entries in theUnreleasedsection ofCHANGELOG.mdunder the new version, and open a pull request. Choosemajor,minororpatchfollowing semantic versioning. The script shows the changes and asks for confirmation before it commits them to a new branch, pushes the branch and opens the pull request:
poetry run python scripts/release.py prepare minor
-
Merge the pull request after it has been approved and CI passes. Do not create the release before the pull request is merged.
-
Update your local
masterbranch and create the GitHub release. The script shows the release notes and asks for confirmation before it creates the release and itsv-prefixed tag at the current commit:
git switch master
git pull --ff-only
poetry run python scripts/release.py release
- The release starts the publish workflow, which first runs the CI workflow. After
the tests and linters pass and the release checks succeed, the workflow waits for
approval to deploy to the
pypienvironment. Before approving, check that the commit of the run is on the default branch and that its.github/workflows/directory is the same as on the default branch.
Saving a draft or publishing a pre-release does not publish anything to PyPI, but changing a pre-release to a release does start the workflow.
If the workflow fails before the deployment, nothing has been uploaded to PyPI. Fix
the problem in a pull request, remove the failed release with
gh release delete v1.2.3 --cleanup-tag and create it again. If the tag cannot be
reused, release a new version instead.
Release infrastructure
PyPI trusted publishing is tied to the workflow file publish.yml and the pypi
environment. The manual approval exists only if the pypi environment has required
reviewers: GitHub creates a missing environment without any protection when a
workflow references it. Do not delete or rename the environment, and do not leave
the environment name blank in the PyPI trusted publisher.