From c1012a20fcde7e0ce7c9edfad3ff7efc5d87a2b6 Mon Sep 17 00:00:00 2001 From: Ako Date: Fri, 14 Aug 2026 20:49:09 +0000 Subject: [PATCH] docs(release-skill): the tag push publishes the release; step 3 edits it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill's step 3 says `gh release create`, but .github/workflows/release.yml fires on any `v*` tag and calls softprops/action-gh-release with generate_release_notes: true. By the time you reach step 3 the release is already public, with the six binaries attached and a body that is the flat PR dump step 3 exists to prevent — so the documented command cannot succeed, and the skill never says the release has already happened. Found while cutting v0.18.0: the tag push published the release, and the curated body had to go on with `gh release edit` after the fact. v0.17.0's published body is the curated section, so this is what the maintainer already does; only the skill was out of date. - Step 2 states plainly that pushing the tag publishes the release, and warns off the two wrong reactions: creating the release first, or deleting and recreating it (which drops the uploaded assets). - Step 3 becomes "replace the generated body", using `gh release edit`. The awk/generate-notes block that builds $BODY is unchanged. - Adds the workflow-failed fallback (`gh release create` with the same body) and an asset check, and splits the checklist line into the two things that now happen separately. Co-Authored-By: Claude Opus 5 (1M context) --- .claude/skills/release.md | 33 ++++++++++++++++++++++++++------- 1 file changed, 26 insertions(+), 7 deletions(-) diff --git a/.claude/skills/release.md b/.claude/skills/release.md index 75cdacb8f..f68946494 100644 --- a/.claude/skills/release.md +++ b/.claude/skills/release.md @@ -84,13 +84,24 @@ Push the commit and tag together: git push origin main --follow-tags ``` +**Pushing the tag publishes the release.** `.github/workflows/release.yml` fires on +any `v*` tag, builds the six platform binaries and calls `softprops/action-gh-release` +with `generate_release_notes: true` — so within a few minutes the release exists, +public, with the binaries attached and a body that is exactly the flat PR dump this +skill tells you not to ship. That is expected; step 3 replaces the body. Do not +try to beat the workflow by creating the release first, and do not delete and +recreate it — that would drop the assets it uploaded. + --- -## 3. Create the GitHub release (curated body + auto tail) +## 3. Replace the generated body (curated body + auto tail) -Do **not** use the web "Generate release notes" button. Run this block — it +The release already exists (see above) with GitHub's generated notes. Step 3 +**overwrites that body** with the curated one — same thing the web "Generate +release notes" button would produce, replaced for the same reason. Run this block +once the release workflow has finished (`gh run list --workflow=release.yml`); it extracts the CHANGELOG section, appends the New Contributors block and a Full -Changelog compare link, and creates the release: +Changelog compare link, and edits the release in place: ```bash VER=v0.15.0 # this release @@ -116,11 +127,18 @@ NEWC=$(gh api "repos/$REPO/releases/generate-notes" \ echo "**Full Changelog**: https://github.com/$REPO/compare/$PREV...$VER" } >> "$BODY" -gh release create "$VER" --title "$VER" --notes-file "$BODY" +gh release edit "$VER" --notes-file "$BODY" rm -f "$BODY" ``` -Verify the rendered body on the releases page, then you're done. +Verify the rendered body on the releases page, and check the six binaries are +attached (`gh release view "$VER" --json assets -q '.assets[].name'`), then you're +done. `gh release edit` touches only the notes — the tag and the uploaded assets +are left alone. + +If the workflow failed and no release exists, the same `$BODY` works with +`gh release create "$VER" --title "$VER" --notes-file "$BODY"`, but fix the +workflow instead of hand-uploading binaries. --- @@ -131,5 +149,6 @@ Verify the rendered body on the releases page, then you're done. - [ ] Entries use the bold-lead-in → em-dash style; related fixes grouped; `(#NNN)` refs - [ ] `make build && make test && make lint` pass - [ ] Commit `docs(changelog): release vX.Y.Z` + annotated tag on `main` -- [ ] `git push origin main --follow-tags` -- [ ] GitHub release created from the CHANGELOG section (not the web generator), with the auto tail +- [ ] `git push origin main --follow-tags` — this publishes the release; the workflow's generated body is replaced in the next step +- [ ] Release workflow finished green and attached six binaries +- [ ] Release body overwritten with the CHANGELOG section (`gh release edit`, not the web generator), with the auto tail