Maintainer release runbook

Maintainer release runbook#

GPN releases are immutable, reviewed scientific artifacts. PyPI publishing is an effect of publishing a GitHub Release; maintainers never upload a wheel or source distribution from a workstation.

Release boundary#

  • Package releases use semantic versions and tags of the form v<version>.

  • Hugging Face model revisions are separate immutable compatibility inputs. A package release does not move or rewrite a model revision.

  • main is the only release branch. The release workflow rejects a tag whose commit is not an ancestor of main or whose name differs from the package version.

  • The pypi environment has no required human reviewer while there is only one active release maintainer. The release event, exact tag, ancestry check, locked build tools, isolated publish job, and PyPI Trusted Publisher are the safeguards.

Before final approval#

  1. Freeze scope and assemble one review PR against main.

  2. Keep Hugging Face asset auditing and card changes outside this release; that work remains tracked separately in issue #81.

  3. Set the final package version and update CHANGELOG.md.

  4. Confirm that the published-model fixture baseline uses the intended immutable revisions. Run the opt-in published-model tests deliberately if a compatibility input changed.

  5. Complete the review packet and external-mutation manifest under release/. Record the exact PR head and tree. A squash merge creates a new commit ID, so approval binds to the reviewed tree; record the resulting main commit and verify its tree immediately after merge.

  6. Obtain explicit approval for the complete code diff and only the pending mutations marked approval_ready. Entries marked deferred are explicitly outside that approval and require a later, separate approval after their blockers are resolved. Do not merge the review PR without explicit maintainer authorization.

Reproduce the release candidate#

Use a fresh clone or worktree checked out at the exact candidate commit so an old dist/ directory cannot contaminate the review. The commands below refuse a dirty checkout and write artifacts to new temporary directories. Record candidate_commit, candidate_tree, and the final hashes in the review packet. Normal tests are network-free.

set -euo pipefail
test -z "$(git status --porcelain)"
candidate_commit="$(git rev-parse HEAD)"
candidate_tree="$(git rev-parse HEAD^{tree})"
artifact_dir="$(mktemp -d)"
rebuilt_wheel_dir="$(mktemp -d)"
uv sync --locked --python 3.13 --extra train --group dev --group docs --group release
uv run pre-commit run --all-files --show-diff-on-failure
HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 uv run pytest
python docs/prepare_notebooks.py
uv run sphinx-build -n -W --keep-going -b html docs docs/_build/release
test -z "$(git status --porcelain)"
uv build --no-build-isolation --out-dir "${artifact_dir}"
uv run --no-sync twine check "${artifact_dir}"/*
uv run --no-sync check-wheel-contents "${artifact_dir}"/*.whl
uv build --no-build-isolation "${artifact_dir}"/*.tar.gz \
  --wheel --out-dir "${rebuilt_wheel_dir}"
uv run --no-sync twine check "${rebuilt_wheel_dir}"/*.whl
uv run --no-sync check-wheel-contents "${rebuilt_wheel_dir}"/*.whl
sha256sum "${artifact_dir}"/* "${rebuilt_wheel_dir}"/*

Install the rebuilt wheel into a clean CPU environment outside the checkout; run gpn --version, gpn --help, import gpn, and call gpn.register_auto_classes(). Record SHA-256 hashes for both distributions in the review packet. The rebuilt wheel hash should match the directly built wheel; if it does not, investigate rather than selecting one artifact for release.

If a change affects training, device placement, precision, or notebook output, also run its documented manual validation in a dedicated Slurm allocation with no more than eight CPUs and one GPU. Never download a whole-genome MSA for release validation.

Merge and publish#

After approval, squash-merge the single reviewed PR. Do not publish while the resulting main tree differs from the approved PR tree. Record the new main commit, verify its tree is the approved tree, and rerun the release-candidate checks on that commit.

  1. Create the annotated historical archive tag/Release only if it is among the approved external mutations.

  2. Create tag v<version> at the exact approved main commit and publish its GitHub Release. Do not run the publishing workflow manually and do not upload distributions yourself.

  3. The release workflow builds once, passes the immutable artifacts between jobs, and publishes with the pypi environment, GitHub OIDC, and PyPI attestations.

  4. Verify the GitHub Actions run, artifact hashes, PyPI metadata and attestations, and a clean pip install gpn==<version> on Python 3.13.

  5. Apply only the separately approved Hub and documentation mutations, then verify their public rendering without moving pinned model revisions.

PyPI files cannot be replaced. If a release is defective, stop downstream mutations, document the incident, yank the affected version when appropriate, and publish a new patch release. Never reuse a tag or version.

Repository rules#

release/main-ruleset.json is the reviewable proposal for main. It requires a PR, the four offline CI contexts, an up-to-date branch, and resolved review threads; each context is bound to the GitHub Actions app rather than accepting a same-named status from another source. It blocks force pushes and deletion. It intentionally requires zero approvals so a solo maintainer is not deadlocked. The absence of bypass actors means the rules also apply to administrators. In an emergency, an administrator may temporarily disable the ruleset in repository settings, document why, restore it immediately, and route the resulting change through a PR.

Research branches remain outside this ruleset and may live indefinitely. Automatic deletion applies only when GitHub recognizes a branch as the merged PR head.