2026-09-18 16:46:45 -04:00
1 changed files with 13 additions and 6 deletions
@@ -91,13 +91,20 @@ When new information about the protocol is discovered, please update the instant
 ## Changelog & release convention
-**Write the entry in the same commit as the work, under `## Unreleased`.  Cut
+**Feature branches do NOT touch `CHANGELOG.md`.  Write the entry on `dev`, as
-the version on `dev` in a dedicated release commit.  Never touch the changelog
+part of finishing the merge, under `## Unreleased`.  Cut the version on `dev` in a
-at a merge boundary.**
+dedicated release commit when you are ready to ship to `main`.**
- **Entry goes in with the change**, not at merge or release time — that is the
+- **The changelog is written on `dev`, never on a feature branch.**  With
-  only moment you still know *why*.  Feature branches edit `CHANGELOG.md`
+  several branches in flight they all edit the same few lines at the top of
-  directly; the occasional conflict is two appended bullets and is trivial.
+  the file and conflict every time.  Writing it once, after the merge, also
  lets it describe what actually *landed* — including anything that changed
  during conflict resolution.
 - ⚠ **The merge is not finished until `## Unreleased` is updated.**  Same sitting,
  not "later" — that is the one failure mode of writing it after the fact.
  Reconstruct from the branch's own commit messages:
  `git log --oneline dev..<branch>` before you merge, or
  `git log --oneline <merge-base>..<branch>` after.
 - **No preamble under `## Unreleased`** — just the `### Added` / `### Changed` /
  `### Fixed` lists.  The themed opening paragraph gets written at release
  time, when the whole release is visible and can be named honestly.  A theme