docs: add a release skill - #237
Merged
Merged
Conversation
Releasing turned out to have four traps and we hit three of them in one afternoon, so they belong somewhere other than a transcript. A valid tag is not a current one. gohai had a perfectly good v1.0.0 and eighty-one commits sitting behind it, and the check that would have caught that is ahead_by rather than the tag list. Go requires three-part versions. nats-client and nats-server were tagged v1.0, which the module proxy ignores, so both served pseudo-versions while looking released. A tag that fires a workflow which cannot authenticate leaves a tag with no release, and the tag is the half that cannot be taken back. The GH_PAT secret expired and nats-client's v1.0.1 landed without one. A version the proxy has fetched is in sum.golang.org permanently. Deleting and re-pushing that tag makes go get report a checksum mismatch, which Go treats as tampering. The skill says to create the missing release against the existing tag instead, and records that re-running the failed workflow does not work because a re-run uses the workflow file as it was at that tag's commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
The rule said any feat: is a minor bump, which is how it produced exactly the wrong answer for both nats repositories on the same afternoon it was written. nats-client had seven feat: commits and nats-server two, so counting made nats-client look like the smaller release. nats-client's seven were Object Store support, core Subscribe and PublishCore, KV CreateOrUpdate and OTel trace propagation. nats-server's two were a justfile recipe and a coverage gate, which no consumer can call. The recommendation that came out was v1.0.1 for the repository with seven API additions and v1.1.0 for the one with none. The rule is now to read the list and ask which entries changed something a consumer can call. The worked example is in the skill, because the failure is not obvious from the rule alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
Every other skill has a README and a row in the repository index. This one shipped with neither, so it was findable only by an agent already looking in .claude/skills. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
/releasefor cutting a release in an osapi-io Go repository. One file.We hit three of its four traps in a single afternoon, so they belong somewhere other than a transcript.
What it records
A valid tag is not a current one. gohai had a perfectly good
v1.0.0and 81 commits sitting behind it. I looked at the tag list, saw a valid semver, and said it was fine. The check that catches this iscompare/<tag>...main --jq .ahead_by, not the tag list.Go requires three-part versions. nats-client and nats-server were tagged
v1.0. The module proxy ignores it, so both servedv0.0.0-2026...pseudo-versions while looking released. An empty@v/liston a repo that has tags is the symptom.A tag that fires a workflow which cannot authenticate leaves a tag with no release, and the tag is the half that cannot be taken back.
GH_PAThad expired and nats-client'sv1.0.1landed without a release. The skill checks the workflow usessecrets.GITHUB_TOKENbefore tagging, and explains why no repo here needs a PAT: none of the.goreleaser.yamlfiles hasbrews:,dockers:,nfpms:orpublishers:, so nothing publishes outside its own repo.A version the proxy has fetched is permanent. It is in
sum.golang.org, which is append-only. Deleting and re-pushing that tag at another commit makesgo getreport a checksum mismatch, which Go treats as tampering rather than as a mistake. The skill says to create the missing release against the existing tag, and records that re-running the failed workflow does not work, because a re-run uses the workflow file as it was at that tag's commit and so does not include a token fix merged afterwards.Version rule
feat:commits since the last tag mean a minor bump,fix:andchore:alone mean a patch. A repo that has never been tagged starts atv0.1.0, becausev1.0.0is a promise about API stability and a library makes that once. The first release of an application is a product decision, so the skill says to ask rather than pick.It also names the two repos that should never be tagged: osapi-justfiles is consumed by curling from
refs/heads/main, and specs is documentation.just testpasses.🤖 Generated with Claude Code
https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c