[joelostblom]

Rework the semi-automated release workflow so official version tags are only created after maintainer approval.

Previously, the workflow created the vX.Y.Z tag and draft GitHub release before review. If maintainers decided not to publish the release, the official tag had to be deleted. This workflow instead prepares a release candidate at a pinned commit and waits for approval through a protected GitHub environment before creating the permanent tag.

Changes

• Split the release workflow into two jobs:
  • prepare-release-candidate
  • create-draft-release
• Pin each release candidate to the exact commit reviewed by maintainers.
• Generate a release notes preview without creating a tag or GitHub release.
• Include the generated notes and candidate commit in the release review issue.
• Remove contributor by @username mentions from the issue preview to avoid notifying non-maintainers.
• Build and publish the documentation preview before requesting approval.
• Gate official tag and draft release creation through the protected release environment.
• Verify that the release environment has at least one required reviewer before creating a tag.
• Allow reviewers to reject a candidate without creating an official tag or GitHub release.
• Create the permanent vX.Y.Z tag at the exact reviewed commit after approval.
• Safely handle retries when the expected tag or draft release already exists.
• Continue regenerating the GitHub release notes when creating the draft so maintainers can compare them with the reviewed preview and make manual edits.
• Block new candidates while an existing release review issue or draft release is open.
• Update RELEASING.md to document the approval flow.

Release Flow

1. The scheduled or manually triggered workflow calculates the next version with Cocogitto.
2. It records the candidate commit, runs the test suite, generates release notes, and publishes a docs preview.
3. It opens a release review issue containing the candidate commit, generated notes, docs preview, and approval link.
4. The create-draft-release job waits for approval through the protected release environment.
5. Rejecting the deployment creates no tag or GitHub release.
6. Approving the deployment creates the immutable version tag at the reviewed commit and creates a draft GitHub release.
7. Publishing the draft release continues to trigger the existing PyPI and documentation publishing workflow.

Repository Setup

Before using the new flow, configure a GitHub environment named release with at least one required reviewer:

1. Go to Settings → Environments.
2. Create or select the release environment.
3. Enable Required reviewers and add the relevant maintainers or team.
4. Optionally enable Prevent self-review.

The workflow fails before creating a tag if the environment has no required reviewers.