chore(changelog): one file per entry in changelog.d/ — merges stop conflicting

[MrChengLen]

Every PR added its changelog entry directly under ## [Unreleased], on the same line each time. So every merge made all other open PRs CONFLICTING, and GitHub runs no pull_request workflows on a conflicting PR.

Since 2026-09-01:

• 47 of 72 merged PRs touched CHANGELOG.md.
• 22 needed the three-commit take-out / merge / put-back dance, which added 66 commits on main.
• More than half of all PR CI runs were cancelled by the re-pushes.

How it works now

New entry	One file per change: changelog.d/<YYYY-MM-DD>-<topic>.md, in the house style (first line ### Fixed — headline, then paragraphs). New files never conflict.
Fold	python scripts/changelog.py moves the files into CHANGELOG.md below the pointer, newest first, and deletes them.
Release	python scripts/changelog.py --release X.Y.Z in the release-prep PR also cuts ## [X.Y.Z] — <date> (docs/development.md, steps 1 and 3). If a PR merges late, running the same command again adds its entry under the heading already cut. An older or empty release is refused.
Guard	tests/test_changelog_fragments.py, inside the required lint-and-test. It checks names and first lines, and fails with the fix spelled out when an entry lands at the top of CHANGELOG.md. It also tests fold, release and refusal on temp files.

The 79 entries already under [Unreleased] stay where they are and move under the next version at release.

Not chosen

• merge=union in .gitattributes. GitHub's server-side merges (merge button, mergeability, update-branch) don't apply repository merge drivers, and git itself stopped reading attributes from HEAD in bare repositories (git 51441e6). It would also never run for API commits.
• Generated release notes only. release.yml already attaches GitHub's PR-title list. As a replacement, it drops most of the content (rationale, operator actions) and the copy inside the signed tarball.
• towncrier / scriv. Their naming and grouping differ from the house style, and they add a dependency for about 50 lines of logic.

Notes

• Unlike CHANGELOG.md, fragments go through the hooks' and the scope guard's content scans. That is the safer direction; changelog.d/README.md says to describe ops-only names instead of spelling them out.
• An open PR that still carries a CHANGELOG.md entry converts with a single commit: set CHANGELOG.md back to its merge-base bytes and add the entry, unchanged, as a fragment.
• The local agent instructions (CLAUDE.md, the ship skill) switch to fragments as soon as this merges. They are not part of the repo.

Verification

• Local: full suite 1667 passed / 80 skipped; ruff clean; gitleaks and the pre-commit scope guard clean.
• Security and code review (commit-review gate) done. Their findings are in: a late-merge re-run, refusal of links and non-fragment files, BOM/CRLF handling, clearer guard messages, and changelog.d/ paths pinned as scanned in test_hook_allowlist_regression.py.
• Release dry-run on a copy of main's CHANGELOG.md: the fragment lands under a new ## [1.2.0] — <date> above the existing [Unreleased] entries, and the pointer stays.

🤖 Generated with Claude Code