opencontainers
gha: enforce CHANGELOG.md entries for PRs
Each release requires going through the list of PRs and trying to parse out what a reasonable changelog entry is (possibly ~6 months after the patch was last discussed and merged), which makes preparing release notes quite time-consuming.
Given that the moment when the patch is merged is when the information about the imapct of a patch is most apparent to the author and reviewers, it seems prudent to require that every PR have a CHANGELOG.md change. Trivial patches can just add a dummy entry in the changelog (in future, we can expand this script to skip over commits that have some special tag to avoid the need for dummy entries).
Signed-off-by: Aleksa Sarai [email protected]
FWIW, in moby we added a changelog section in the PR template so that we can extract those. Depending on the PR type, it's still optional, but perhaps variations thereof are possible (eg don't enforce if it's just a dependency bump); at least that prevents the merge-conflicts and allows tweaking changelog entries. https://github.com/moby/moby/blob/06eadccf2fd03ed4aca8f467f38eb6dd7be48922/.github/PULL_REQUEST_TEMPLATE.md?plain=1#L22-L34
https://github.com/moby/moby/blob/06eadccf2fd03ed4aca8f467f38eb6dd7be48922/.github/workflows/validate-pr.yml#L16-L93
@thaJeztah Ah, I didn't know it was that automated. That might be a good way of doing it, let me take a look...
EDIT: Is the changelog collation also automated?
It's definitely still a bit of work in progress, but perhaps good for inspiration / building blocks to come with something useful.
I think many projects struggle with this; it's always hard to find the right balance between preparing the work as part of the PR (but tying to keep it low threshold), and still have some flexibility (also for those cases where PRs are superseded by follow ups, so not all changes may still be relevant).
containerd uses a release tool that has some magic (but ultimately uses a toml file to collect change logs / allow preparing the release notes); it works, and also handles dependency updates, but perhaps could be combined with something like the above.
Kubernetes does something similar with a release-note tag in the description. You can update it after the PR is merged, it is just queried by a tool (not sure which one, though).
Like 15 years ago (or maybe more), I did a simple way to automate it: just create an entry out of each merge commit, using the mrege text. Github does merge commits all the time, so just make sure that the PR title is clear and that will be used for the changelog entry. That was enough for that internal project, but here we usually have long changelog entries and one PR touches several sections sometimes too. The "advantage" was that it just needs the git repo, not the github api nor anything, it was very very simple.
I'm fine with any way to automate it. I do think it needs to be automated, right now it is just too much toil.
Maybe we can agree to start with a changelog file for each release branch? Like changelog-1.2, changelog-1.3, etc. so we avoid the "forward porting" changes, that is messy and doesn't scale well (specially with several supported release branches).
Yeah, PR title and/or (first line of) commit usually isn't enough for "notable" updates. The importance of changes may also not always be known at the time the PR was created; if course it should be, but I've seen many examples (here, and other projects), where some PR turned out to be release-notes worthy, even if the PR at time it was reviewed didn't seem very important.
And, of course, there's the reverse, where a contributor (well intended) could write a lengthy release-note for a typo-fix.
For those cases, having a section in the PR description that can be modified after the fact can be useful, but still have a "full release notes" generated from the git diff and/or a GitHub diff URL
Maybe we can agree to start with a changelog file for each release branch? Like changelog-1.2, changelog-1.3, etc. so we avoid the "forward porting" changes, that is messy and doesn't scale well (specially with several supported release branches).
It depends a bit what readers expect; do we want a single history, or are we OK with release-notes in a branch to only contain release notes for the current release, possibly with links to the latest version in each of the release branches? Using separate files would still require those files to be forward-ported to main, otherwise the main branch would have be incomplete for patch releases for prior versions.
If we'd only keep release-notes for the "current" release as maintained in a branch, that would largely mean "scrubbing" the previous release when the release branch is created.