Contributing

Add a release note when a pull request changes the API, supported Python versions, package installation, or documented behavior. Put each distinct change in its own docs/changelog.d/+short-name.<category>.rst file. The name need not contain a pull request number; release preparation links it to the squash-merged pull request.

Use feature for new behavior and Python support changes, change for changes to existing behavior, bugfix for corrections, and doc for documentation changes users need to know about. Use breaking, security, performance, deprecation, removal, or packaging when those describe a user-facing change more precisely. The rendered changelog calls the first four categories Added, Changes, Fixed, and Documentation. Empty categories are omitted.

For example, a change to backend path handling can use docs/changelog.d/+backend-paths.bugfix.rst:

Resolve in-tree backend paths relative to the project root.

Keep a fragment focused on its effect for users, and leave out the pull request link and any credit. Release preparation adds the link, and credits come from the pull request’s commit authors and Co-authored-by co-authors; it also runs release-creator contributors to list first-time contributors in the changelog. A maintenance-only pull request can use the skip news label; the label can be added after the pull request opens. Bot pull requests without a fragment get that label automatically. If a bot pull request does include a fragment, the bot is credited when it is the pull request’s only author.

Run prek run --all-files before pushing. Release preparation runs the same hooks on the assembled changelog before it creates a commit and tag.