Problem
The current changelog ritual (#131) has every user-visible-behavior PR add an entry to CHANGELOG.md's single [Unreleased] section. This repo routinely develops several PRs in parallel (parallel implementer agents). When 2+ of those each edit the same [Unreleased] region, they conflict — a merge conflict, or a forced re-sync collision under the strict up-to-date policy on develop.
(Config/tooling/docs-only PRs correctly get no changelog entry, so they don't contribute to this — the conflict is specifically between multiple user-visible-behavior PRs.)
Options (pick one)
- Changelog fragments — recommended, industry best practice. Each PR adds a small, uniquely-named file under
changelog.d/ (e.g. changelog.d/165.fixed.md) and never edits CHANGELOG.md directly, so two PRs never touch the same file → zero conflicts. A release step (towncrier / changesets / a tiny local script) assembles fragments into the release section at cut time and deletes them. Atomic with each PR and conflict-free.
- Interim rule, no tooling. Until fragments land: when 2+ PRs run in parallel, do NOT have each edit
CHANGELOG.md. Add the entry only in the last PR of the batch, or open a single dedicated changelog PR at batch/session end. A solo PR may keep its atomic entry (no conflict possible).
Acceptance criteria
References
Problem
The current changelog ritual (#131) has every user-visible-behavior PR add an entry to
CHANGELOG.md's single[Unreleased]section. This repo routinely develops several PRs in parallel (parallel implementer agents). When 2+ of those each edit the same[Unreleased]region, they conflict — a merge conflict, or a forced re-sync collision under the strict up-to-date policy ondevelop.(Config/tooling/docs-only PRs correctly get no changelog entry, so they don't contribute to this — the conflict is specifically between multiple user-visible-behavior PRs.)
Options (pick one)
changelog.d/(e.g.changelog.d/165.fixed.md) and never editsCHANGELOG.mddirectly, so two PRs never touch the same file → zero conflicts. A release step (towncrier / changesets / a tiny local script) assembles fragments into the release section at cut time and deletes them. Atomic with each PR and conflict-free.CHANGELOG.md. Add the entry only in the last PR of the batch, or open a single dedicated changelog PR at batch/session end. A solo PR may keep its atomic entry (no conflict possible).Acceptance criteria
changelog.d/+ an assembly step, wired into the release cut / Release-cut documentation sweep (do with the next develop→main release) #132 docs sweep and the About-dialog "What's new" build (CHANGELOG.md (Keep a Changelog) + changelog visible in the app #131); delete fragments on assembly.References