Release Process

Release Process

Overview

Releases are versioned from Git tags using the Poetry dynamic versioning plugin. Do not edit version in pyproject.toml. CI builds artifacts and publishes based on the GitHub Release type.

Prerequisites

• You have maintainer permissions on the repo and PyPI/TestPyPI.
• Ensure changes are merged to main and CI is green.
• No manual version bump is needed.

Tagging and GitHub Releases

You can create tags either locally or directly in the GitHub Releases UI.

• Stable tag (SemVer): vX.Y.Z (e.g., v0.3.0)
• Pre-release tag: vX.Y.Z-rc.N (e.g., v0.3.0-rc.1)

Options:

• Local CLI: git tag -a vX.Y.Z -m "Release X.Y.Z" && git push origin vX.Y.Z
• GitHub UI: Create a new Release, set the tag (new or existing), and mark as “pre-release” for RCs.

Note: The workflows fetch full history and tags, so tags created in the GitHub UI are supported.

CI Behavior

• Pre-release GitHub Releases (checkbox on): publish to TestPyPI.
• Final GitHub Releases (checkbox off): publish to PyPI.
• Version is derived from the tag (PEP 440 style). Example: v1.2.3-rc.1 -> 1.2.3rc1.

Local Verification (optional)

• Build with resolved version locally:
  • poetry self add "poetry-dynamic-versioning[plugin]"
  • poetry install --no-root
  • poetry build
• Inspect dist/* filenames to confirm the computed version.

Troubleshooting

• Version shows 0.0.0 locally: ensure the plugin is installed and a tag is reachable.
• CI did not publish: confirm the Release pre-release flag and that the tag matches vX.Y.Z or vX.Y.Z-rc.N.