ADR-0004: Version-keyed changelog, written at release time
Status: Accepted
Date: 2026-05-30
Scope: core (every repo that releases)
Context
The Expenses backend once kept rich, hand-written per-feature “patch notes”
(docs/patch-notes/YYYY-MM-DD-topic.md) — endpoints, payloads, validation, a
frontend-summary table. That format was a mini-spec per change and didn’t
survive the release cadence: it lapsed at the v1.0 era while the backend reached
v1.41.0, and the surviving notes described a since-replaced architecture
(ddl-auto: update, pre-Flyway). The lesson: a change log only stays current if
producing it is nearly free and tied to a moment that always happens.
We already have the ingredients for that: conventional-commit messages
(feat:/fix:/refactor:…), version tags on main, and the /release skill
that inspects commits since the last tag to decide the bump.
Decision
Each repo maintains a CHANGELOG.md at its root, keyed to released
versions (newest first), in Keep a Changelog
style:
Entries are written/updated at release time, derived from the conventional
commits since the previous tag — not hand-authored per feature mid-development.
The detailed per-feature docs/patch-notes/ practice is superseded and
removed; deep design context lives in ADRs instead.
History was backfilled from git tags (best-effort; terse old commits yield
sparse entries).
Consequences
The changelog is a near-free byproduct of releasing, so it should actually
stay current this time.
Quality tracks commit-message hygiene — another reason to keep writing clear
conventional subjects.
Follow-up: the /release skill should append the new version’s section as
part of the release-branch step, so it’s automatic rather than remembered.
Example
Real code from the repos — optional
Agents: safe to skip. The Decision above is the specification; everything below is
illustration. Skipping this block costs you nothing normative and saves tokens. Expand it
when you need the shape rather than the rule — porting the pattern to a new project, or
answering “what does this actually look like”.
## v2.41.1 — 2026-09-12### Fixed- **v2.41.0 showed a blank page to every signed-in user.** When the app asks you to accept a new version of the Terms, the API refuses every other request until you do — but the app still loaded its pages behind the prompt, and one of them crashed on the refused response before the prompt could appear. The app now waits for that check and then shows either the prompt or the app, never both.
Written for the person who was affected, not for the person who fixed it. It names what
they saw — a blank page — before it explains anything, and it says which version did it.
No commit hashes, no file paths, no component names. “Waits for that check” is the shape
of the fix at the level a user can verify; whether that was a guard, a gate or a reordered
effect is in the diff, and the diff is one git log away for anyone who needs it.
The entry is keyed to the version, so a user on v2.41.0 can find out whether their problem
is fixed, and it admits the regression was ours rather than describing it as an
improvement. Most changelogs would have written “improved Terms acceptance flow”.