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:

.. code-block:: bash

    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:

#. Build the distributions used for the release.
#. Publish them successfully to PyPI.
#. Create the ``v$VERSION`` Git tag for the released commit.
#. 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.