docs: write the changelog on dev, not on feature branches

Reverses the "entry goes in with the work" rule from two commits ago. That was
wrong on the evidence: of the docs(changelog) commits in history, 3 of 4 in
seismo-relay and 2 of 4 in Terra-View were made directly on dev. The rule was
generalized from one unrepresentative commit rather than from the pattern.

It also caused the exact problem it was supposed to avoid. With four worktrees
in flight, every branch edits the same few lines at the top of CHANGELOG.md;
feat/ach-rescue-on-connect and feat/sensor-check-h5 collide on that file and
nothing else. Writing the entry once, on dev, after the merge removes the
whole conflict class.

The second benefit is accuracy: an entry written after the merge describes
what actually landed, including anything that changed during conflict
resolution. The sensor-check branch is a live example — its Unreleased
preamble describes a release that no longer looks like that.

The failure mode of writing it later is forgetting, so the merge is explicitly
not finished until Unreleased is updated — same sitting, reconstructed from the
branch commit messages.

Unchanged: no preamble under Unreleased, the mandatory operational consequence,
and cutting the version on dev when ready to ship to main.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qcu9ByJfuKBQxmrWb8rSrN
This commit is contained in:
2026-09-18 18:52:17 +00:00
co-authored by Claude Opus 5
parent a42e8d3651
commit 0408c37866
+13 -6
View File
@@ -91,13 +91,20 @@ When new information about the protocol is discovered, please update the instant
## Changelog & release convention ## 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` / - **No preamble under `## Unreleased`** — just the `### Added` / `### Changed` /
`### Fixed` lists. The themed opening paragraph gets written at release `### Fixed` lists. The themed opening paragraph gets written at release
time, when the whole release is visible and can be named honestly. A theme time, when the whole release is visible and can be named honestly. A theme