Contributing

You’re welcome to come and bake delicious macaroons with us :)

This project uses uv and prek.

There are multiple ways of interacting with the project.

I want to run the code quality tools

# Run once:
$ prek run --all-files

# Install pre-commit hooks
$ prek install

I want a venv to play locally

$ uv sync

Use uv sync --python=3.x if you want to work on a specific Python version.

There is no need to activate .venv manually. Run project commands through uv run instead.

I want to run the tests

The easiest way to run the tests on a single python version is:

$ uv run pytest

Coverage is enforced at 100% on merged matrix coverage in CI. Branches gated by Python-version checks do not need to be covered in every local test run, as long as they are covered by at least one CI matrix job. When you run pytest locally, you’ll get a terminal report at the bottom as well as a more detailed HTML report in htmlcov/index.html. In PRs, a summary of the coverage report is posted as a comment by the CI.

Acceptance tests and fixtures

Acceptance tests in tests/acceptance/ are snapshot-like tests of the built HTML.

If the normalized HTML output changes, tests/acceptance/changelog.html is rewritten by the test before it fails. Review the updated fixture, then run the test again and commit the fixture change if it is expected.

Those tests also use VCR cassettes from tests/acceptance/cassettes. If the GitHub API fixture data needs to be refreshed, use:

# Re-record interactions in the selected test run
$ uv run pytest --record-mode=rewrite

I want to build the documentation

Build with:

$ scripts/docs
$ uv run python -m webbrowser docs/_build/html/index.html

If Sphinx’s console output is localized, and you would rather have it in English, use the environment variable export LC_ALL=C.utf-8.

I want to hack around

Adapt the commands in /scripts to your liking.

Core contributor additional documentation

Release a new version

Make a GitHub Release. The rest is automated.

Note

If you need to edit the name or body of a release in the GitHub UI, don’t forget to also rebuild the stable and latest doc on readthedocs.