Our current approach to keeping a changelog is to add entries in an ‘Unreleased’ section, and then rename that section when there is a release. This means that any PR that spans a release needs to be updated every time there is a release, lest it be merged into the renamed section instead of the current ‘Unreleased’ section. There's no check to make sure that such a merge doesn't happen other than the vigilance of maintainers, and it's extra work for PR authors for the PRs that span at least one release. Personally, I think it's frustrating enough just staving off bitrot for PRs that are over a year old; moving the changelog entry around is simpler but a little more demoralizing because it's a self-created problem.
My ideal, as I've said before, would be to generate the changelog from commit messages (by strictly following some commit message convention), but the feedback on that, IIRC, was that we want to write our changelogs for a different audience than we want to write our commit messages for, and while I still don't agree I can respect that I'm in the minority. But that aside, there are surely other things we can do to reduce the maintenance burden on long PRs.
For example, we could keep a CHANGELOG.md for released changes, and a CHANGELOG.unreleased.md for unreleased changes, and prepend the latter into the former on release. That would keep PRs from potentially merging into the wrong part of the changelog.
Better still, we could do the above but instead of one CHANGELOG.unreleased.md, we could keep a folder full of snippets, one for each PR, named by category and PR number (feature-1234.md, fix-1235.md, breaking-1236.md). Then, not only would the above problem be solved, but we would also solve the related problem that PRs will conflict with each other if they both want to append to the same place in the changelog.
I recognize that the manual changelog was introduced in part to reduce the burden during releases; I don't think these proposals move the needle too far back in the other direction—I'll volunteer to write the script to merge changelog fragments into the released changelog, if that helps—but what do others think?
Our current approach to keeping a changelog is to add entries in an ‘Unreleased’ section, and then rename that section when there is a release. This means that any PR that spans a release needs to be updated every time there is a release, lest it be merged into the renamed section instead of the current ‘Unreleased’ section. There's no check to make sure that such a merge doesn't happen other than the vigilance of maintainers, and it's extra work for PR authors for the PRs that span at least one release. Personally, I think it's frustrating enough just staving off bitrot for PRs that are over a year old; moving the changelog entry around is simpler but a little more demoralizing because it's a self-created problem.
My ideal, as I've said before, would be to generate the changelog from commit messages (by strictly following some commit message convention), but the feedback on that, IIRC, was that we want to write our changelogs for a different audience than we want to write our commit messages for, and while I still don't agree I can respect that I'm in the minority. But that aside, there are surely other things we can do to reduce the maintenance burden on long PRs.
For example, we could keep a
CHANGELOG.mdfor released changes, and aCHANGELOG.unreleased.mdfor unreleased changes, and prepend the latter into the former on release. That would keep PRs from potentially merging into the wrong part of the changelog.Better still, we could do the above but instead of one
CHANGELOG.unreleased.md, we could keep a folder full of snippets, one for each PR, named by category and PR number (feature-1234.md,fix-1235.md,breaking-1236.md). Then, not only would the above problem be solved, but we would also solve the related problem that PRs will conflict with each other if they both want to append to the same place in the changelog.I recognize that the manual changelog was introduced in part to reduce the burden during releases; I don't think these proposals move the needle too far back in the other direction—I'll volunteer to write the script to merge changelog fragments into the released changelog, if that helps—but what do others think?