diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index b96de691..2ff29356 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -15,6 +15,13 @@ The `branch-diff` tool must be installed globally: npm install branch-diff -g ``` +Fetch and fast-forward **both** branches before doing anything else. Comparing a +stale `v5.x` against a stale `main` silently produces a wrong commit list: + +``` +git fetch origin && git checkout v5.x && git pull && git checkout main && git pull +``` + ## Steps ### 1. Identify commits to cherry-pick @@ -25,9 +32,36 @@ Use the `branch-diff` tool to list commits on `main` not yet applied to `v5.x`: branch-diff v5.x main ``` -Review the output with the user. Skip: -- Version bump commits (e.g. "Bump package version on to 6.0.0-pre") -- Commits that would result in empty cherry-picks (already applied or superseded) +Its GitHub issue-lookup errors go to stderr; the commit list is on stdout. PR numbers +appear in the trailing URL (`.../pull/393`), *not* as `(#393)` — parsing the `(#NNN)` +form instead picks up PR references that happen to appear in commit titles. + +`branch-diff` matches commits, not content, so it reports a substantial number of +**false positives** — commits whose changes are already on `v5.x`. Do not cherry-pick +these. They fall into three classes: + +**a. Squash-merged releases.** Releases 5.14.2, 5.14.3 and 5.14.4 were squash-merged +rather than rebased, so every commit they contained lost its identity and is reported +forever. This set is closed and will not grow — treat all of these as already released: + +| Release | Proposal | PRs subsumed | +|---|---|---| +| 5.14.2 | #331 | 284, 310, 311, 315, 316, 317, 320, 323, 324, 325, 326, 327, 329 | +| 5.14.3 | #334 | 328, 332 | +| 5.14.4 | #337 | 333, 335, 336 | + +**b. Superseded dependency bumps.** A Dependabot bump that never landed on `v5.x`, which +later picked up an equal-or-newer version of the same package directly. Cherry-picking one +would *downgrade* the branch. Recognise these by comparing the package version in +`v5.x:package.json` against the bump's target — skip when `v5.x` is at or ahead of it. +(Examples seen so far: #140, #344, #348, #349, #350.) + +**c. The `main`-only version bump.** #154 moved `main` to `6.0.0-pre`. It must never be +cherry-picked onto a 5.x release branch. + +Anything left after removing those three classes is a genuine candidate. Note that being +old is *not* by itself evidence of a false positive: #352 sat below all of these and was a +real, unapplied commit. Classify by the rules above, not by age. Confirm the list of commits with the user before proceeding. @@ -54,6 +88,13 @@ Create a git worktree from the current repo, checking out a new branch `v$VERSIO git worktree add ../pprof-nodejs-v5 -b v$VERSION-proposal v5.x ``` +The path is usually still occupied by the previous release's worktree. Once that +proposal's PR is merged, it is safe to clear — verify it is clean and merged first, then: + +``` +git worktree remove ../pprof-nodejs-v5 && git branch -D v-proposal +``` + All subsequent steps run in the worktree directory. ### 4. Cherry-pick commits @@ -66,7 +107,30 @@ git cherry-pick ... If a cherry-pick has conflicts, stop and resolve with the user. -### 5. Create the version bump commit +### 5. Verify the selection against `main` + +Before bumping the version, diff the worktree against `main`: + +``` +git diff --stat main -- . +``` + +The goal is **minimal divergence**: ideally this reports nothing but `package.json` and +`package-lock.json` (the version, plus any dev-dep bump this release includes). + +This is the check that validates step 1, and it is worth doing carefully — it is how #352 +was caught, a genuinely unapplied commit that a plausible-looking age heuristic had +written off as a false positive. Any *other* file appearing here means one of two things: + +- a real commit was wrongly classified as a false positive — cherry-pick it, or +- the divergence is deliberate — say so explicitly in the PR body rather than leaving it + silently unexplained. + +Note that a class-(b) superseded bump correctly shows up as a `package.json` / +`package-lock.json` difference where `v5.x` is *ahead* of `main`. That is expected and +should be left alone. + +### 6. Create the version bump commit Bump the version in package.json and package-lock.json using npm, then commit: @@ -76,7 +140,11 @@ git add package.json package-lock.json git commit -m "v$VERSION" ``` -### 6. Push and create a PR +Keep this commit last on the branch. If a further cherry-pick turns out to be needed after +this point, drop the version commit (`git reset --hard HEAD~1`), apply the cherry-pick, +then re-run the bump — rather than stacking the new commit on top of the release commit. + +### 7. Push and create a PR Push the branch and create a PR targeting `v5.x`: