docs(release): make the two-PR flow, the production smoke, the ledger and the UI tag explicit - #2299
Merged
Merged
Conversation
#2298) The release skill described a v2 release as three steps and left four things a release actually depends on implicit or absent: that it is two pull requests against two different bases, the production smoke of the release candidate, the ledger artifact the maintainers review, and where a smoke finding gets fixed. It also gave only the `git tag` path, which is the fallback rather than the norm. Restructure it around PR 1 -> PR 2 -> Release: - a "The shape" table contrasting the two PRs by branch, base, contents, verification and merge condition, plus why they must not be folded together and why PR 1 merges before PR 2 is opened; - step 2 broken into the tree-hash check and production smoke, the ledger's structure, and the fix-on-`v2/main` rule that keeps the merge tree byte-identical to `origin/v2/main`; - step 3 leading with the GitHub UI path, keeping the CLI commands as the by-hand equivalent. Docs only. The `npm audit fix`, `--no-git-tag-version`, tag-`origin/main`, no-`v`-prefix and #2010 warnings are all preserved. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01RsmR1iQstcrEzJFmgZXGLi Signed-off-by: cliffhall <cliff@futurescale.com>
There was a problem hiding this comment.
🟢 Approval recommended
The change is documentation-only and the updated procedure is internally consistent and aligns with the stated release workflow constraints.
Pull request overview
Updates the release skill documentation to reflect the real v2 release procedure, making the two-PR workflow, production-build smoke testing, the smoke ledger artifact, and the GitHub UI-driven tagging/release steps explicit so maintainers don’t cut a technically-correct-but-operationally-wrong release.
Changes:
- Reframes the release as PR 1 (audit + fixes + version bump on
v2/main) → PR 2 (milestone merge intomain+ production smoke + ledger) → GitHub Release. - Adds explicit production smoke instructions (including the tree-hash identity check) and defines the expected ledger artifact structure.
- Clarifies that smoke findings are fixed via
v2/mainPRs and re-merged (never by committing on the merge branch), and that tagging/releases are normally done via the GitHub UI.
File summaries
| File | Description |
|---|---|
.claude/skills/release/SKILL.md |
Expands the release procedure doc to explicitly capture the two-PR flow, production smoke + ledger, and UI-driven release/tag creation. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
🟢 Approval recommended
The change is documentation-only and the updated procedure is coherent and consistent with the PR description, with only a minor wording nit noted.
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
| | Base | **`v2/main`** | **`main`** | | ||
| | Carries | the `npm audit` report, **any fixes the audit forces**, and the **version bump** — all three, one PR | the milestone's work, arriving whole from `v2/main`. **No commits of its own.** | | ||
| | Verified by | `npm run local:gate` | `npm run local:gate` **plus** a hand-driven smoke of every contribution in the milestone, from the **production build**, written up as a **ledger artifact** | | ||
| | Merged when | reviewed and green | the ledger is reviewed by the maintainers and clean | |
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
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.
Closes #2298
.claude/skills/release/SKILL.mddescribed a v2 release as "three steps" — audit + bump, merge, tag — which is accurate about the commands and silent about four things the release actually depends on. Someone following it as written can get every step technically right and still cut the release wrong.What was missing, and what replaces it
v2/mainwith no bump on it)origin/v2/main, then drive every closed contribution from the production build — packaged bin and built bundles, notvite dev— in a dedicated worktree with a real install. States that "its tests pass" is not evidence here, because the gate already said thatv2/main, reaching the merge branch by re-merging — never as a commit on the merge branch, which would break the byte-identical-tree property that makes the smoke mean anything (#2000 → #2092, #2215 → #2216–2224). The skill had the bump version of this rule (#2010) but not the findings versionx.y.z→ Targetmain), keeping the CLI commands as the by-hand equivalent. The tag-origin/mainwarning now notes the UI path avoids that trap by constructionThe
descriptionwas rewritten (and quoted, per the#/:rule) to name the two-PR flow, the ledger and the UI release.Not changed
Docs only — no code, no gate, no workflow. Every existing warning is preserved verbatim:
npm audit fixand thetsup/esbuilddowngrade,--no-git-tag-version, never copying a version out of the file, tagorigin/mainnotHEAD, novprefix, and the #2010 rationale for bumping onv2/mainfirst.releasestaysdisable-model-invocation: true, so it carries no eval cases and adds nothing to the listing budget (verify:skillsstill reports 3234/4000).Verification
npm run local:gatein a dedicated worktree with its own fullnpm install.The first run came back exit 1 on a single Storybook story —
SkillsScreen.stories.tsx:495, the collapse-then-reopen geometry assertion (1 failed / 524 passed). That is the #2278 race the test's own comment describes, and it is not attributable to this branch:git diff origin/v2/main...HEAD --name-onlylists exactly one file,.claude/skills/release/SKILL.md, and no client source. Re-runningnpm run local:storybookon the same tree: 123 files / 525 tests, all passed. Every other stage was green on the first run.🤖 Generated with Claude Code
https://claude.ai/code/session_01RsmR1iQstcrEzJFmgZXGLi