Release Workflow Design

This page records the intended release policy generated by xcookie. These are project design decisions, not missing hardening tasks. Read this before changing release.yml generation.

Release trigger

The normal release command is:

git push origin main:release

The release branch push is the deliberate release action. Maintainers are not expected to create a version tag manually.

The commit reaching release is expected to have already passed review and CI on its way to main. The release workflow may rebuild distribution artifacts, but it intentionally does not rerun the full test matrix. xcookie does not require byte-identical promotion of artifacts retained from the earlier CI run, a release manifest, or checksum provenance between those runs.

Ordering and failure policy

The intended order is:

  1. Build the distributions used for the release.

  2. Publish them successfully to PyPI.

  3. Create the v$VERSION Git tag for the released commit.

  4. Create the GitHub release associated with that exact version tag.

This order is deliberate. A bad or incomplete PyPI publication cannot be replaced, while a Git tag or GitHub release can be repaired after a later step fails. Do not move tag creation before live PyPI publication merely to make the workflow look more transactional.

GitHub release association

A release-branch workflow has a triggering ref such as refs/heads/release. That ref must never be passed to the GitHub release action as its release tag. Doing so reuses a branch-associated draft across versions and can accumulate older versioned wheel and sdist assets in the same GitHub release.

After PyPI succeeds, xcookie resolves TAG=v$VERSION, creates that tag, and passes the same value to softprops/action-gh-release. The displayed release name and tag_name must both use the resolved version tag, not github.ref.

Retry behavior

The post-PyPI portion must be safe to retry. If v$VERSION already exists and points to the current release commit, the workflow should continue and recreate or update the GitHub release. If the tag points to a different commit, the workflow must fail rather than move or overwrite it automatically.

Scope discipline

Do not expand a focused release fix into a different release model without an explicit policy decision. In particular, the following are optional designs, not current requirements:

  • rerunning the full test matrix during release;

  • retaining and promoting byte-identical artifacts from main CI;

  • commit-addressed release manifests or cross-workflow checksum verification;

  • requiring maintainers to create version tags manually;

  • moving tag creation before PyPI publication.