Skip to content

Write a release procedure runbook (doc/dev/release-process.md) #573

@utensil

Description

@utensil

The 0.6.0 cycle surfaced several non-obvious steps that aren't documented anywhere. This issue tracks writing a doc/dev/release-process.md that a maintainer can follow end-to-end.

Related prior art: #517, v0.5.2rc1 release, PRs #561 and #562.

What the doc should cover:

Policy

  • Always cut an RC first to validate the full pipeline before the final release
  • RC goes to PyPI as a pre-release; Zenodo skips pre-releases

Branch and version bump

  • Create a branch (e.g. utensil/X.Y.Z-rc1), bump _version.py to X.Y.ZrcN (PEP 440) — the version must exactly match the tag that will be pushed (see the 0.5.1 incident in Release 0.5.2 #517)
  • After RC validates, create a second branch for the final bump: X.Y.ZrcNX.Y.Z

Changelog

  • The :release: marker in doc/changelog.rst uses semantic_version internally — PEP 440 RC suffixes like 0.6.0rc1 are invalid semver and will break the RTD build. Omit the marker for RCs; add it only for the final release.
  • test/.nbval_sanitize.cfg version regex must match all suffix patterns (e.g. rc\d+|-dev) — validate this before tagging

Creating the release

  • RC: gh release create vX.Y.ZrcN --prerelease --title "vX.Y.ZrcN" --notes "..."
  • Final: gh release create vX.Y.Z --title "vX.Y.Z" --notes "..."
  • The CI Create release and send to PyPI job triggers on the tag automatically

Post-release checks

  • PyPI: verify at https://pypi.org/project/galgebra/#history
  • Zenodo: auto-archives on full releases but the webhook is unreliable — verify and trigger manually from zenodo settings if needed
  • Close the milestone
  • Update README and user-facing docs referencing version/install instructions (separate PR)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions