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
docs: make the release cadence explicit
2026-09-18 18:52:17 +00:00 · 2026-09-18 18:04:54 +00:00 · 2026-09-18 18:02:59 +00:00
1 changed files with 45 additions and 0 deletions
@@ -37,6 +37,51 @@ current design:

 ---

+## Changelog & release convention
+
+Adopted 2026-09-18, to match seismo-relay and Terra-View.  SLMM had no written
+practice before this — earlier releases used ad-hoc commits like
+`chore: version bump`.  This is the standard going forward.
+
+**Feature branches do NOT touch `CHANGELOG.md`.  Write the entry on `dev`, as
+part of finishing the merge, under `## [Unreleased]`.  Cut the version on `dev` in a
+dedicated release commit when you are ready to ship to `main`.**
+
+- **The changelog is written on `dev`, never on a feature branch.**  With
+  several branches in flight they all edit the same few lines at the top of
+  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
+  written when the first item landed is stale by the third.
+- ⚠ **State the operational consequence**, **including when it is "none."**
+  Silence is ambiguous; "none" is information.  For this repo that means:
+  - **DB migration** — whether a `migrate_*.py` script is needed, which one,
+    and whether it is safe to re-run.  These live at the repo root and are
+    easy to forget at deploy time.
+  - **Meter-connection impact** — anything touching the NL-43/NL-53 TCP path,
+    polling cadence, or the monitor fan-out.  The meter has a **single TCP
+    slot**, so a change that bounces the connection is an operational event,
+    not just a code change.
+- **Releases are cut on judgement, not on a schedule or a merge.**  `Unreleased`
+  is the staging area for whatever is going into the next release; when enough
+  has accumulated to be worth shipping, it gets a number and a date.  Nothing
+  about a merge to `dev` triggers a release.
+- **Cutting a release** is its own `chore(release): vX.Y.Z` commit on `dev`,
+  renaming `## [Unreleased]` → `## [X.Y.Z] - YYYY-MM-DD` and bumping the
+  version in `app/main.py` (the FastAPI `version=` argument).
+- **`main` carries only released versions.**  No `## [Unreleased]` section
+  there; it lands via the `dev` → `main` PR.
+
+---
+
 ## Layout

 ```