Problem
Every PR appends to ## [Unreleased] in CHANGELOG.md. When several PRs are open at once, merging one puts the others in conflict. For 0.3.8, parallel PRs left the changelog alone and put their entry in the PR description instead, to be collected in #206. That works, but it relies on someone collecting the entries before the release.
Proposal
Each PR adds its own fragment file. The release step assembles the fragments into CHANGELOG.md.
- File name:
changelog.d/<issue>.<section>.md, where section is one of added, changed, deprecated, removed, fixed, security. The content is the entry text in the current style: a bold one-line summary, then the details.
scripts/changelog_release.py: before promoting ## [Unreleased], insert the fragments under their headings in Keep a Changelog order. Append the issue link from the file name, then delete the fragments. The release workflow already commits CHANGELOG.md; it must also commit the removal of changelog.d/*.tests/test_changelog_release.py:
- cover the assembly: ordering, the issue link, and several fragments for one section;
test_the_repository_changelog_can_be_released should count pending fragments, because ## [Unreleased] will usually be empty between releases.
- Docs: describe the convention in
docs/DEVELOPMENT.md so outside contributors follow it.
- Optional: a CI check that a PR either adds a fragment or carries a
no-changelog label.
Why not towncrier or commit-based generation
The entry format is already project-specific, and the release notes are built from the bold summaries. Extending our own script keeps one code path.
Generating the changelog from commit titles would lose the detail the entries carry, such as behaviour changes and migration notes.
Not in scope
The 0.3.8 entries collected in #206.
Problem
Every PR appends to
## [Unreleased]inCHANGELOG.md. When several PRs are open at once, merging one puts the others in conflict. For 0.3.8, parallel PRs left the changelog alone and put their entry in the PR description instead, to be collected in #206. That works, but it relies on someone collecting the entries before the release.Proposal
Each PR adds its own fragment file. The release step assembles the fragments into
CHANGELOG.md.changelog.d/<issue>.<section>.md, where section is one ofadded,changed,deprecated,removed,fixed,security. The content is the entry text in the current style: a bold one-line summary, then the details.scripts/changelog_release.py: before promoting## [Unreleased], insert the fragments under their headings in Keep a Changelog order. Append the issue link from the file name, then delete the fragments. The release workflow already commitsCHANGELOG.md; it must also commit the removal ofchangelog.d/*.tests/test_changelog_release.py:test_the_repository_changelog_can_be_releasedshould count pending fragments, because## [Unreleased]will usually be empty between releases.docs/DEVELOPMENT.mdso outside contributors follow it.no-changeloglabel.Why not towncrier or commit-based generation
The entry format is already project-specific, and the release notes are built from the bold summaries. Extending our own script keeps one code path.
Generating the changelog from commit titles would lose the detail the entries carry, such as behaviour changes and migration notes.
Not in scope
The 0.3.8 entries collected in #206.