release

name	release
description	Cut a release of genlayer-testing-suite. Bumps version, updates CHANGELOG, tags, pushes — CI then publishes to PyPI and creates the GitHub Release. Use when a human asks "release v0.29.x" or "ship a new version".

Release skill — genlayer-testing-suite

This repo follows a branch-per-major release model. There is no auto-bump on push. A release happens when a human (or you on their behalf) runs scripts/release.sh on the target stable branch.

When to use this skill

User asks anything like:

• "release v0.29.1"
• "ship a patch"
• "tag the latest fix as a release"

If they ask "publish to PyPI directly" — refuse and point at this flow. The repo doesn't have an unprotected PyPI push path; the tag is the only release entry point.

What this repo's release model expects

• Branches are named after the major they ship: v0.29 (current stable). When v0.19 opens, the previous v0.29 stays read-only for back-ports.
• Tags live within those branches: v0.29.1, v0.29.2, ...
• Semver-zero rule: this package is still on a 0.x line, so the MINOR component is the breaking-change boundary. 0.18 → 0.19 IS a major bump. scripts/release.sh refuses both minor and major keywords without --allow-major while we're on 0.x.
• A major (= minor on 0.x) bump means cutting a new branch (v0.19) — not tagging on top of the current one.
• CHANGELOG.md is updated in the release commit (python-semantic-release with explicit version).
• publish.yml fires on the tag push and does the PyPI publish + GitHub Release.

Steps

1. Confirm intent with the user.

   • Which version? If unspecified, ask whether it's patch or explicit.
   • If they say "minor" or "major" while we're on 0.x, surface that this means cutting a new branch — confirm before proceeding.

2. Switch to the target branch + sync.

   git checkout v0.29
   git pull --ff-only origin v0.29
   

   If the working tree isn't clean, stop and surface what's there.

3. Verify the head is shippable.

   • Latest CI green:

     gh run list --branch v0.29 --commit "$(git rev-parse HEAD)" --limit 1
     

   • Inspect commits since the previous tag for surprises:

     git log "$(git describe --tags --abbrev=0)..HEAD" --oneline
     

4. Run the release script.

   scripts/release.sh <X.Y.Z>     # or patch
   

   It bumps pyproject.toml, updates CHANGELOG.md, commits chore(release): vX.Y.Z, tags vX.Y.Z, and pushes both the branch commit and the tag. It will NOT publish to PyPI — CI handles that.

5. Watch the publish workflow.

   gh run watch
   

   If publish.yml fails (typical: tag/pyproject mismatch, expired PYPI_API_TOKEN, build failure), report verbatim and stop. Don't retry blindly.

6. Confirm on PyPI.

   pip index versions genlayer-test
   

   The latest version should match. Report back with the version and the GitHub Release URL.

Things to refuse

• Minor or major bump on 0.x without --allow-major. Those are major bumps in semver-zero and belong on a new branch.
• Releasing from main — main is retired.
• Hand-editing pyproject.toml to bump the version — the script keeps pyproject, the CHANGELOG entry, the commit message, and the tag in lockstep.
• Publishing a tag where publish.yml failed — fix the underlying issue, re-cut the release (delete the bad tag locally and on origin, re-run the script).

Roll-back

If a release shipped but is broken:

1. Don't yank from PyPI unless someone with elevated permissions has assessed the impact — PyPI yank is reversible but signals "skip this" to installers and you'll want a follow-up patch up first.
2. Ship a follow-up patch via the same flow (scripts/release.sh patch).
3. After the fixed version is live, optionally yank the bad version:

   pip install pkginfo twine
   # use pypi.org web UI to yank — there's no CLI in current PyPI flow
   

Why no auto-bump?

Previously push: main triggered python-semantic-release, which would auto-bump and tag whenever a feat:/fix: commit landed. Two failure modes that fix-on-merge can't address:

• Conflated decisions — "merge this PR" silently meant "ship to PyPI".
• Major bumps that slip through (BREAKING CHANGE in a PR body produces a 0.X → 0.X+1 bump while on 0.x, which is a major).

Manual + scripted puts a checkpoint between the two without losing the bump-tag automation.