Files
poli0981andClaude Opus 5 39a0c54f05 docs: the changelog gets a directory, and a session gets a version
Two conventions, written down where each is enforced rather than remembered.

**`changelog/`, one file per major line.** A single growing file is the thing this
avoids: a reader should open `1.x.md` and find their version without scrolling past
releases they do not care about. Root `CHANGELOG.md` is a pointer, because two places to
write a release note is one place to forget.

A pre-release line gets its **own** file, named for the line it leads to, and is not
folded in when that line goes stable — the beta file is what says *when* a behaviour
changed during the run-up, and merging it would double the length of the file people
actually read while losing exactly that.

The split rule is stated in terms of **reading length rather than release count**, since
that is the property being defended: past roughly 600 lines, split into contiguous minor
ranges and leave the old name as a stub so no link breaks. Range files are never
renumbered — `1.0-1.4.md` does not become `1.0-1.6.md` at the next split.

Entries are backfilled for 1.0.0, 1.1.0 and 1.2.0, written for a *user*: what changed,
what they have to do about it, and — for 1.2.0 — that the legal gate will appear once,
which is the kind of thing a release note exists to say before someone reports it as a
bug. Deliberately no commit counts: a number written about the repository inside the
repository goes stale on commit, which AI-DISCLOSURE learned three times.

**One session, one slice, one version.** Depth over breadth, plus a hotfix release when
one is needed. It is in CLAUDE.md's conventions because that is what the next session
reads first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-18 12:07:57 +07:00

371 B

Changelog

Kept in changelog/, one file per major line, newest release first.

This file is a pointer, not a copy. A single growing changelog is the thing the directory exists to avoid, and two places to write a release note is one place to forget.