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>
371 B
371 B
Changelog
Kept in changelog/, one file per major line, newest release first.
- 1.x — 1.0.0 onward
- Conventions and the split rule
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.