From 2fabf84d4d984b49c6c7c0a8a72e536a0c59a430 Mon Sep 17 00:00:00 2001 From: serversdown Date: Fri, 18 Sep 2026 17:39:56 +0000 Subject: [PATCH] docs: adopt a changelog convention, and make Unreleased follow it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Brian asked what the standard is; there wasn't a written one, only a de facto pattern in the history. This writes it down in CLAUDE.md and fixes the one place the repo already diverged from it. 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. The entry goes in with the change because that is the only moment you still know why. Two additions beyond what the history already did: No preamble under ## Unreleased. The themed opening paragraph gets written at release time, when the whole release is visible and can be named honestly. The current one proved the point — "Blastware Event/FFT-Report parity: the FFT, the USBM compliance chart, and the sensor self-check" was accurate when the first item landed and stopped being accurate once rescue-on-connect landed under the same heading. Removed here; the release commit writes a new one covering everything actually in the release. And the operational consequence is now mandatory on any entry touching the codec, the waveform store, or the DB — including when it is "none". This repo's changelog is how future-you learns whether a deploy costs two hours on the NAS, so silence is ambiguous and "none" is information. The old preamble's load-bearing half is preserved as an explicit ### Migration block rather than dropped with the prose around it. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Qcu9ByJfuKBQxmrWb8rSrN --- CHANGELOG.md | 20 ++++++++++---------- CLAUDE.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8dbbfd2..4abc959 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,16 +6,6 @@ All notable changes to seismo-relay are documented here. ## Unreleased -**Blastware Event/FFT-Report parity — the FFT, the USBM compliance chart, and -the sensor self-check.** Three analyses Blastware derives from event data, -reverse-engineered against BE12844 (MiniMate Plus) reports and reproduced in -seismo-relay: the compliance chart and the sensor-check strip now render on -the event-report PDF, and the FFT reproduces Blastware's FFT Report. All three -are additive and read from data already on disk — the `.h5` samples and the -retained raw BW binary — so there is **no `.h5`/DB change, no migration, and no -backfill**: a report regenerated for an existing event simply gains the new -panels. - ### Added - **Rescue-on-connect for `bridges/ach_server.py`** — `--stop-monitoring` (SUB 0x97), `--disable-ach` (SUB 0x2C read → 0x7E write → 0x7F confirm) and @@ -85,6 +75,16 @@ panels. --- +### Migration + +**None.** Every change here is additive and reads from data already on disk — +the `.h5` samples and the retained raw BW binary. No `.h5`/DB change, no +schema change, no migration, no backfill, and **no `TOOL_VERSION` bump**: a +report regenerated for an existing event simply gains the new panels, and the +`ach_server` rescue flags don't touch the codec. + +--- + ## v0.30.0 — 2026-09-12 **The series-4 correctness release** — the Thor / Micromate counterpart to diff --git a/CLAUDE.md b/CLAUDE.md index 05ec9ea..5ed6a15 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -89,6 +89,36 @@ 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 +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** on any entry touching the codec, the + waveform store, or the DB — **including when it is "none."** "requires + `backfill_sidecars.py` + `backfill_event_shape.py`, ~2 h on the NAS", + "`TOOL_VERSION` bumped", "no schema change, no migration". Silence is + ambiguous; "none" is information. This repo's changelog is how future-you + learns whether a deploy costs two hours. +- **Cutting a release** is its own `chore(release): vX.Y.Z — ` commit on + `dev`, renaming `## Unreleased` → `## vX.Y.Z — YYYY-MM-DD` and touching: + `CHANGELOG.md`, `pyproject.toml`, the version line in `CLAUDE.md` and + `README.md`, and `minimateplus/event_file_io.py` (`TOOL_VERSION`) **when the + codec changed** — that constant gates `.h5` regeneration. +- **`main` carries only released versions.** No `## Unreleased` section there; + it lands via the `dev` → `main` PR. `main` lagging `dev` by a version is + normal. + +--- + ## Architecture: three-tier conceptual model seismo-relay is a **suite of cooperating components**, not a single app.