release

/release

Use this skill when you are ready to cut a release.

Pre-release checklist

Run all five checks. All must pass before tagging:

uv run pytest -q                        # tests
uv run ruff check src tests             # lint (use --fix to auto-correct import sort)
uv run mypy src                         # type-check
uv run vulture src --min-confidence 80  # dead code
uv run lint-imports                     # architecture boundaries (import-linter)

Release order

Never tag before the branch push is confirmed.

# 1. Bump version in pyproject.toml
git add pyproject.toml
git commit -m "chore: bump version to vX.Y.Z"

# 2. Push to main first — confirm it landed
git push origin main

# 3. Only then tag and push — this is what triggers the release
git tag vX.Y.Z
git push origin vX.Y.Z

Do not create the release by hand

Pushing the tag starts .github/workflows/release.yml, which runs the full check suite, builds, creates the GitHub release with gh release create --generate-notes, publishes to PyPI via OIDC, and attaches SLSA provenance.

Running gh release create yourself will make the workflow's own call fail, because the release already exists. Watch the run instead:

gh run watch "$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"

Release notes are generated by GitHub from the commits since the previous tag.