From a96c17ffe1f9b4ee18ffd08e5637a38d9a515e40 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 29 Mar 2026 22:12:18 -0700 Subject: [PATCH] docs: clarify branch-scoped VERSION/CHANGELOG after merging main Add explicit rules: merging main doesn't mean adopting main's version. Branch always gets its own entry on top with a higher version number. Three-point checklist after every merge. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 0ea420c7..af180980 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -258,6 +258,18 @@ not what was already on main. 3. Does an existing entry on this branch already cover earlier work? (If yes, replace it with one unified entry for the final version.) +**Merging main does NOT mean adopting main's version.** When you merge origin/main into +a feature branch, main may bring new CHANGELOG entries and a higher VERSION. Your branch +still needs its OWN version bump on top. If main is at v0.13.8.0 and your branch adds +features, bump to v0.13.9.0 with a new entry. Never jam your changes into an entry that +already landed on main. Your entry goes on top because your branch lands next. + +**After merging main, always check:** +- Does CHANGELOG have your branch's own entry separate from main's entries? +- Is VERSION higher than main's VERSION? +- Is your entry the topmost entry in CHANGELOG (above main's latest)? +If any answer is no, fix it before continuing. + CHANGELOG.md is **for users**, not contributors. Write it like product release notes: - Lead with what the user can now **do** that they couldn't before. Sell the feature.