Skip to content

docs(release): point to the release files; rc first, rerun, never move a tag - #56

Merged
tobert merged 3 commits into
mainfrom
docs/release-procedure
Nov 9, 2026
Merged

tobert merged 3 commits into
mainfrom
docs/release-procedure

Conversation

@tobert

@tobert tobert commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Shortens README.md "Releases" to a pointer to release.yml and .goreleaser.yml, whose comments explain each step. It adds four rules that the code does not show:

  • Tag v0.X.Y-rc.1 first. An rc does not update the Homebrew tap or latest.
  • The tap push needs the repository secret HOMEBREW_TAP_GITHUB_TOKEN.
  • If a run fails after the GitHub release exists, fix the cause and run gh run rerun.
  • Do not move a published tag. Release the next patch version.

AGENTS.md "Releases" now has an rc step before the final tag on the same commit. It also says that only a maintainer can set the tap token.

The v0.6.0 release taught these rules. GoReleaser now gets the pushed tag (#54), so an rc and the final tag can share a commit.

An earlier draft documented the full procedure in README.md. A kaibo review comment on this PR covers that draft. The draft was too long; the files the README points to already explain those steps.

🤖 Generated with Claude Code

@tobert

tobert commented Nov 9, 2026

Copy link
Copy Markdown
Owner Author

kaibo review (cast deepseek: deepseek-flash)

The review checked the README.md and AGENTS.md "Releases" sections against release.yml, .goreleaser.yml and the AGENTS.md style rules.

Factual findings. All three are fixed in this PR:

  1. "The release candidate does not use the tap token" was wrong. The preflight (release.yml:65-73) stops any tag run when the secret is empty. skip_upload: auto (.goreleaser.yml:149-150) skips only the tap push for a prerelease.
  2. "This snapshot run builds and tests everything" was wrong. release.yml has no go test step; ci.yml:62-63 runs the tests.
  3. "A snapshot does not resolve a tag" was not exact. version_template: "{{ incpatch .Version }}-SNAPSHOT-..." reads the latest tag.
  4. A gap in the checks: gh release view does not show "Latest". The check now uses gh release list --json tagName,isLatest, because gh release view --json isLatest is not a valid field.

Style findings. These are applied: "everything" replaced with the named artifacts, sentences with two or three topics split, one term for the rc, "does not match the tag", the full image name in AGENTS.md, and the AGENTS.md pointer sentence.

Not changed: the error strings 401 Bad credentials and denied: permission_denied are copied from the v0.6.0 run logs (run 42421835716 attempt 2, run 42421043115).

Confirmed correct: the tag formats, rc gating for the tap and latest/X.Y, GORELEASER_CURRENT_TAG, the version check before the image push, replace_existing_artifacts, the snapshot publish gates, and the image entrypoint for docker run ... version.

Why: Amy: "let's make sure it's documented in README.md and (briefly)
AGENTS.md". The v0.6.0 release needed three attempts and steps that were
not documented.
Approach: README "Releases" now has the procedure (CHANGELOG, rc tag, check,
final tag on the same commit, check), recovery for a 401 from the tap and a
ghcr permission_denied, the tap token command that tests before it stores,
and the sha256-* install box note. AGENTS.md has short steps and two hazards.
Learned: kaibo review: an rc run still needs the secret (the preflight checks
it), release.yml runs no tests, and `gh release view` has no isLatest field.
Next: The next release follows this text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🤖 Reviewed by DeepSeek (deepseek-flash) via kaibo
@tobert tobert changed the title docs(release): document the rc → final procedure, checks and recovery docs(release): point to the release files; rc first, rerun, never move a tag Nov 9, 2026
Why: Amy: "should replace 'Amy' with @tobert or 'maintainers'".
Approach: AGENTS.md already says "Ask a maintainer"; use the same term.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@tobert
tobert merged commit 0bc3aa8 into main Nov 9, 2026
2 checks passed
@tobert
tobert deleted the docs/release-procedure branch November 9, 2026 15:29
Why: Amy: "you added way too much to the README.md, just say where the
process is, say a lot less, we can infer most of it and just need pointers".
Approach: README points to release.yml and .goreleaser.yml, whose comments
explain each step, and lists four rules the code does not show. The token
scope is in release.yml:62-64 and .goreleaser.yml:133-134.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tobert added a commit that referenced this pull request Nov 9, 2026
Why: Amy: "we'll get a 0.6.2 rolling to do an e2e". We agreed on 0.6.1,
because 0.6.0 is the last release.
Approach: Two terse bullets. The actions bumps (#55) and the docs (#56)
do not change what users get.
Next: Tag v0.6.1-rc.1, then v0.6.1 on the same commit to test #54.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant