Captures the cut-and-publish workflow currently encoded only in
scripts/publish-banger-release.sh and the CHANGELOG patterns. Covers:
- Release artefacts + R2 paths + the install.sh-at-bucket-root
contract.
- Trust model recap (cosign pubkey pinned in both verify_signature.go
and scripts/install.sh; drift check enforced by the publish script).
- Pre-flight checklist: green smoke, CHANGELOG entry with the right
Keep-a-Changelog headings, link-table bump, explicit callout when
unit files changed (banger update swaps binaries, not units).
- Cut order: publish first, tag after, verify from a clean machine.
- Verification-release rule: any fix to runUpdate / unit templates /
helper-daemon restart sequencing requires an immediate no-op +1
release so a host on the buggy version can update to it and observe
the fix live with the new binary in the driver seat. v0.1.3 and
v0.1.5 are the existing examples.
- Patch vs minor: minor = exposed API/contract change (vsock guest-
agent protocol, CLI flag removal, RPC shape, non-forward-compatible
store schema); everything else is patch.
- Sibling catalogs: kernel + golden-image entries are go:embed-ed,
so they piggyback on the next banger release.
- Mid-release recovery for signature drift, partial rclone, re-cut,
and bad-tag cleanup (never reuse a version).
AGENTS.md gets a one-liner pointer so the maintainer guide surfaces
the runbook without duplicating it.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Thales Maciel
759fa20602