Release Management

Overview

We use towncrier to manage release notes and cocogitto (cog) to select the next semantic version from Conventional Commits. The package version itself is still derived from Git tags via hatch-vcs, so there is no manual version file to edit.

Publishing is already automated in .github/workflows/release.yml on pushed v* tags. The maintainer’s local work is to run the checks, aggregate the release notes, and create the correct tag.

The documentation page describes generating newsfragments.

The Release Workflow

A maintainer should perform the final checks locally before pushing the release tag, but the actual build and PyPI publish are CI-driven.

Building the Changelog

The final build aggregates all fragments into CHANGELOG.rst. First preview the next version, then render the changelog for that exact tag.

uv sync --extra test --extra release
uv run --extra test pytest -m pure
uv run --extra test pytest --pep723-check -m pep723 --override-ini="python_files=" --ignore=rgpycrumbs/chemgp rgpycrumbs/
uvx prek run -a -vvv
pixi run -e docs docbld

uvx cocogitto cog bump --dry-run --auto
uvx towncrier build --version "1.7.1"

Checklist

  • Ensure the tree is clean after aggregating fragments into the changelog.

  • Verify the previewed cog version matches the intended release.

  • Do not manually edit package version metadata; hatch-vcs reads the tag.

  • Use plain X.Y.Z for the changelog heading even though the Git tag is vX.Y.Z.

Atomic Commits and Tagging

The release notes remain an explicit commit. After that, cog applies the next tag directly to the current commit. This works well with hatch-vcs, which derives the package version from the tag itself.

git add CHANGELOG.rst docs/newsfragments
git commit -m "release: v1.7.1"
uvx cocogitto cog bump --auto
git push origin main --tags

Distribution

After the tag push, the release workflow runs the actual distribution steps:

  • pure tests plus the PEP 723 dependency checks

  • lint

  • docs build

  • uv build

  • PyPI publish via trusted publishing

  • GitHub release creation with attached artifacts

GitHub releases

The workflow already creates the GitHub release from the pushed tag, so there is no separate manual draft step unless you want to edit the autogenerated release notes afterward.