Release Runbook

Overview

Execute a clean release workflow: verify repo state, run tests, bump versions, tag, push, publish a GitHub release, and update downstream artifacts after the tag exists.

Workflow

1) Preflight

• Check repo state: git status -s and git diff should be clean.
• Confirm remote: git remote -v and current branch.
• Verify GitHub auth: gh auth status.
• Ensure required tools are available (git, gh, jq, language runtimes).

2) Decide the version bump

• Choose SemVer bump (major/minor/patch) based on changes.
• Locate version references and update them before tagging:

- Common files: VERSION, package.json, pyproject.toml, Cargo.toml, go.mod, setup.cfg, setup.py, Formula/*.rb (url only), README.md badges. - Use rg -n "version|VERSION|version" to find references.

3) Run tests (or a documented smoke test)

• Prefer project-defined tests (README/Makefile/CI):

- make test, npm test, pytest, go test ./..., etc.

• If no tests exist, run a minimal smoke check and record it in the release notes.
• Looper-specific smoke check (if repo contains bin/looper.sh):

- Create a temp project, set MAX_ITERATIONS low, run the loop, and verify it exits cleanly.

4) Commit release changes

• Stage and commit all changes required for the release.
• Keep commit messages Conventional Commits unless the repo specifies otherwise.

5) Tag and push

• Create an annotated tag on the release commit:

- git tag -a vX.Y.Z -m "vX.Y.Z"

• Push code and tag:

- git push origin <branch> - git push origin vX.Y.Z

6) Publish GitHub release

• Create a release from the tag:

- gh release create vX.Y.Z --title "vX.Y.Z" --notes "<summary>"

7) Update Homebrew formula (if present)

• Only after the release tag exists (tarball is published).
• Compute the new sha:

- curl -L -s https://github.com/<org>/<repo>/archive/refs/tags/vX.Y.Z.tar.gz | sha256sum | awk '{print $1}'

• Update Formula/*.rb with the new url and sha256.
• Commit and push the formula update.

Notes

• Tag should point to the release commit; formula updates are separate and can land after the tag.
• If tests fail, stop and fix before tagging.
• Keep release notes short and factual (highlights + testing performed).

Helper Script

Use scripts/release.sh to automate the end-to-end release flow.

Examples:

# Tag, push, release, and update Formula/*.rb
scripts/release.sh --version 0.2.0 --test-cmd "make test"

# Use a custom bump command and a VERSION file
scripts/release.sh --version 1.4.0 --bump-cmd "npm version minor --no-git-tag-version" --version-file VERSION

Notes:

• --version-file overwrites files with the raw version string (no leading v).
• Formula updates are performed after the tag exists; set --skip-formula to skip.
• Use --dry-run to preview commands without executing.