Repository navigation
Changelog entries now go to changelog.d/, one file per PR #1280
doobidoo
announced in
Announcements
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Between v11.12.0 and v11.13.0, 19 pull requests were merged. Exactly one of them left an entry under
## [Unreleased]inCHANGELOG.md. I reconstructed the other 18 from commit messages and PR bodies while cutting the release, days after the fact, for changes I had not written.The reason was not discipline. Every entry went to the top of the same file, so every open branch edited the same lines and conflicted with every other open branch. A convention that punishes you for following it does not get followed.
What changed
A change under
src/now needs a file of its own:<number>is your PR or issue number,<category>is one ofadded,fixed,removed,internal. The file holds one markdown list item. Two pull requests never touch the same file, so there is nothing left to conflict.Example, from
changelog.d/1277.fixed.md:Write the symptom and what it does now. Not the patch. Somebody reading the release notes in six months needs to recognise the bug they are hitting.
At release time
scripts/release/collect_changelog.pymerges the fragments into[Unreleased]under their category headings and deletes them. Your wording reaches the release notes as you wrote it.What is exempt
Release version bumps, anything from Dependabot, and any PR carrying the
skip-changeloglabel. Docs-only and test-only changes need nothing, since the gate only looks atsrc/. Be aware that the label takes effect on the next event the PR emits, so push a commit after labelling. Re-running the job replays the payload from before the label existed.Caveat
The gate is new. Greptile found nine real holes in the first version across four review rounds, including one where a fragment could pass CI and then vanish at release time, and two where my own fix for the previous round opened the next gap. There may be more. If it blocks a change it should not, use the label and open an issue with the case.
Format and categories:
changelog.d/README.md. Contributor steps:CONTRIBUTING.md.Credit to @filhocf, who read the merged workflow off main and used it in two PRs within half an hour, before this post existed.
All reactions