From 5d0f31e584407c70123a58f285a223511bc9ccea Mon Sep 17 00:00:00 2001 From: serversdown Date: Fri, 18 Sep 2026 18:02:59 +0000 Subject: [PATCH] docs: adopt the changelog & release convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brian asked for one standard across the three repos. seismo-relay and Terra-View already had the pattern in their history; SLMM did not — earlier releases used ad-hoc commits like "chore: version bump" with no [Unreleased] section. So this introduces the practice here rather than documenting it, and says so. The rule: write the entry in the same commit as the work under [Unreleased], cut the version on dev in a dedicated chore(release) commit, never touch the changelog at a merge boundary. No preamble under [Unreleased] — the themed paragraph gets written at release time when the whole release is visible. The operational consequence is mandatory, including when it is "none". For SLMM that is two things: whether a root-level migrate_*.py script is needed and whether it is safe to re-run, and whether the change bounces the meter connection — the NL-43 has a single TCP slot, so that is an operational event rather than just a code change. Version lives in app/main.py, the FastAPI version= argument. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qcu9ByJfuKBQxmrWb8rSrN --- CLAUDE.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 129973e..1b4855e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,6 +37,40 @@ 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. + +**Write the entry in the same commit as the work, under `## [Unreleased]`. Cut +the version on `dev` in a dedicated release commit. Never touch the changelog +at a merge boundary.** + +- **Entry goes in with the change**, not at merge or release time — that is the + only moment you still know *why*. Feature branches edit `CHANGELOG.md` + directly; the occasional conflict is two appended bullets and is trivial. +- **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. +- **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 ```