From a95c39eea508b845b8580f1a7c5f33c1633eaf63 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 28 Apr 2026 17:09:18 -0700 Subject: [PATCH] =?UTF-8?q?docs(claude):=20sharpen=20CHANGELOG=20rule=20?= =?UTF-8?q?=E2=80=94=20diff=20between=20main=20and=20ship?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Codifies what was already implicit in the existing "Never orphan branch-internal versions" + "Only document what shipped between main and this change" sections, but with sharper language and concrete NEVER examples. The rule: a CHANGELOG entry is the diff between main and the shipping branch — what users get when they upgrade. NOT how the branch got there. Branch-internal version bumps, mid-branch bug fixes, plan review outcomes, and patch narratives all belong in PR descriptions and commit messages, not in CHANGELOG. Adds explicit examples of phrasing to NEVER use: - "v1.X had a bug that v1.Y fixes" (mentions a branch-internal version) - "The shipping headline of v1.X was broken because..." (apologizes for never-released state) - "Pre-fix tests encoded the broken behavior" (contributor's victory lap, not user benefit) - "Two surgical edits, both in the dispatch path" (micro-narrative of the patch) The constructive replacement: describe the released system as a property, not as a fix. "Browser-skills run end-to-end with the expected tab-access semantics." If a property is worth calling out, document it in the trust-model section, not as a "we fixed X" callout. Pairs with feedback_no_shame_changelog and feedback_changelog_harden_against_critics memories — entries should read as a flex even to a hostile screenshotter, never admit prior breakage. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index cd08caf4..c0f07f69 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -489,6 +489,31 @@ MINOR again on top (e.g., main at v1.14.0.0, your branch lands v1.15.0.0). own version bump and CHANGELOG entry. The entry describes what THIS branch adds — not what was already on main. +**The CHANGELOG entry is the diff between main and the shipping branch — what users +get when they upgrade. NOT how the branch got there.** A reader landing on the entry +should learn what they can do now that they couldn't before; they should not learn +about the branch's internal version bumps, the bugs we caught and fixed mid-branch, +the plan reviews we ran, or the commits we squashed. That is branch development +narrative. It belongs in PR descriptions and commit messages, not CHANGELOG. + +**Never reference branch-internal versions in a CHANGELOG entry.** If your branch +bumped VERSION from v1.5.0.0 → v1.5.1.0 → v1.6.0.0 during development and only the +final v1.6.0.0 ships to main, the entry must read as if v1.5.1.0 never existed. +Concretely, NEVER write: +- "v1.5.1.0 had a bug that v1.6.0.0 fixes" — readers don't know about v1.5.1.0; it's + a branch-internal artifact. +- "The shipping headline of v1.5.1.0 was broken because..." — same reason. From main's + perspective, v1.5.1.0 was never released. +- "Pre-fix tests encoded the broken behavior" — that's a contributor's victory lap, + not a user benefit. +- "Two surgical edits, both in the dispatch path" — micro-narrative of the patch. + +Instead, describe the released system: "Browser-skills run end-to-end with the +expected tab-access semantics." If a property of the shipped system is worth calling +out (e.g., "skill spawns get permissive tab access; pair-agent tunnel tokens require +ownership"), document it as a property, not as a fix. The shipped system is what +the user gets; the path to that system is invisible to them. + **When to write the CHANGELOG entry:** - At `/ship` time (Step 13), not during development or mid-branch. - The entry covers ALL commits on this branch vs the base branch.