Skip to content

Commit 843f18b

Browse files
justin808claude
andauthored
Teach /update-changelog to drop RC-only regression fixes (#1125)
## Summary When collapsing prereleases (e.g., `v10.1.0-rc.0` → `v10.1.0-rc.1`), a fix for a bug introduced by a PR that only ever shipped in the prerelease train is invisible to consumers of the last stable release. Listing it under the new RC/release header just adds noise. This PR updates `.claude/commands/update-changelog.md` so the command: - **Excludes RC-only regression fixes** in the "Do NOT add entries for" list (with a forward-reference to the detailed rule) - **Adds a dedicated step** in the RC/beta collapse procedure that walks through detecting and dropping these entries, with the rc.0 → rc.1 example - **Requires surfacing dropped entries in the final summary** so the maintainer can override case-by-case (e.g., keep one for RC testers) ## Motivation Caught while stamping `v10.1.0-rc.1` in #1124. PR #1120 fixes a regression introduced by PR #1110 (gem-file allowlist), which itself only shipped in `v10.1.0-rc.0`. Users on `v10.0.0` jumping straight to `v10.1.0-rc.1` never see the bug, so PR #1120's fix is internal RC churn rather than a user-facing change. The previous version of the command would have kept it in the changelog. ## Test plan - [ ] Maintainer review of the prose - [ ] Try the next `/update-changelog rc` invocation and confirm the model now asks about (or silently drops) RC-only regression fixes <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Low risk: documentation/procedure updates only, affecting how changelog entries are curated during RC/beta version stamping. > > **Overview** > Updates the `/update-changelog` instructions to **avoid standalone changelog entries for RC-only regression fixes** (fixes that only undo a regression introduced earlier in the same prerelease train). > > Adds a dedicated prerelease-collapsing step that directs the maintainer to **merge such fixes into the original prerelease PR entry (or drop them if redundant)**, and to **explicitly list any merged/dropped items in the final summary** for review/override. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 08b4488. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent ba495cd commit 843f18b

1 file changed

Lines changed: 11 additions & 0 deletions

File tree

.claude/commands/update-changelog.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,7 @@ When stamping a version header (`release`, `rc`, or `beta`), compute the next ve
8383
- Test updates
8484
- Documentation fixes (unless they fix incorrect docs about behavior)
8585
- CI/CD changes
86+
- **RC-only regression fixes as standalone entries**: a fix for a bug that was introduced by another PR which itself only shipped in an unreleased prerelease (e.g., `v10.1.0-rc.0`). Users upgrading from the last stable version to the next prerelease/stable never see the bug, so a standalone "Fixed X" entry is internal RC churn. Instead, **merge the fix into the original PR's entry** so the description matches the final shipped state (credit both PRs, update any details the fix changed). Only drop the entry entirely if the fix has nothing left to merge into the original. See "Filtering RC-only fixes when collapsing prereleases" below.
8687

8788
## Formatting Requirements
8889

@@ -298,6 +299,16 @@ When the user passes `rc` or `beta` as an argument (or when creating a prereleas
298299
- Update version diff links to point from the last stable version to the new prerelease
299300
- This keeps the changelog clean with a single prerelease section that accumulates all changes since the last stable release
300301

302+
5. **Filtering RC-only fixes when collapsing prereleases**: while collapsing, scan the post-rc commit list for fixes that exist only to repair a regression introduced earlier in the same prerelease train. **Default to merging them into the original PR's entry** rather than keeping them as standalone "Fixed X" entries:
303+
- For each `Fixed`/`Security` entry under Unreleased that came from a post-rc commit, identify the PR it fixes (usually referenced in the entry body, the PR body, or the linked issue)
304+
- If the referenced PR is **already listed** in the prerelease section being collapsed (i.e., it shipped only in an RC, not in the last stable version), the fix is RC-only churn — choose one of:
305+
1. **Merge (preferred)**: fold the fix into the original PR's entry. Credit both PRs in the link list (e.g., `[PR #1110](…), [PR #1120](…)`), and update any details the fix changed (e.g., the allowlist now includes `package.json`) so the entry reflects the final shipped state. This is almost always the right choice because stable consumers will see the merged behavior, not the intermediate regression.
306+
2. **Drop**: if there is nothing meaningful left to merge (e.g., the fix only restores prior behavior without changing the original entry's description), remove the fix's standalone entry.
307+
- If the referenced PR shipped in the last stable version (or earlier), keep the fix as its own entry — real users running the stable release will see the bug
308+
- When uncertain, ask the user before merging or dropping
309+
- Example: rc.0 ships PR #1110 (gem allowlist `CHANGELOG.md, MIT-LICENSE, README.md, gemspec, lib, sig`). Post-rc.0, PR #1120 adds `package.json` to the allowlist to fix `shakapacker:check_node`. When stamping rc.1, **merge** — credit both PRs and add `package.json` to the allowlist in the original entry. (Not "drop" — the description otherwise would lie about what ships.)
310+
- Always **list merged/dropped RC-only fixes in the final summary** so the user can override case-by-case
311+
301312
**Note**: The new version header must be inserted **immediately after `## [Unreleased]`** (see Step 4). This ensures correct ordering of version headers.
302313

303314
### For Prerelease to Stable Version Release

0 commit comments

Comments
 (0)