docs: adopt the changelog & release convention

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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Qcu9ByJfuKBQxmrWb8rSrN
This commit is contained in:
2026-09-18 18:02:59 +00:00
co-authored by Claude Opus 5
parent 518e6f287a
commit 5d0f31e584
+34
View File
@@ -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
```