Start the release notes for 2.22 #20878
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kaos
approved these changes
May 7, 2024
Co-authored-by: Andreas Stenius <[email protected]>
huonw
added a commit
that referenced
this pull request
May 8, 2024
This is CI in service of continually maintaining our detailed changelog, i.e. have long form descriptions of unreleased features listed in the "latest" `docs/notes/2.*.x.md` file, so we don't have to write this in a batch as part of prepping the release. The detailed changelog for a big release is a better for users than listing PR titles (as we do for each incremental dev release), because it gives space for linking to docs, giving code examples etc. This PR adds CI to enforce that every PR, either: - changes a `docs/notes/` file, usually in the form of adding a paragraph or two to `docs/notes/2.22.x.md` (or similar, whatever the latest `main` release is) - explicitly opts out via a label (`category:internal` or `release-notes:not-required`) This PR tries to be a minimal MVP of a process improvement. The key bit of this CI is enforcing an _explicit_ opt-out: we can say "let's maintain a changelog as we go" without this PR, but I think we'll forget to do it all the time, if we don't have a computer reminding us. ## Example of how this works in practice ### Feature or fix worth including in release notes 1. Someone opens a PR 2. The release notes CI step fails 3. The author or reviewer notices this and suggests that release notes be included in the appropriate `docs/notes/2.*.x.md` file 4. The PR is updated with release notes, CI reruns and passes now ### Minor change not worth including in release notes 1. Someone opens a PR 2. The release notes CI step fails 3. The author or reviewer notices this and a maintainer tags the PR with `release-notes:not-required` 4. The release notes CI step can be rerun and passes now ### Demo of error Demonstration of a failure when this PR was tagged with `category:new feature` (instead of `category:internal`): https://github.com/pantsbuild/pants/actions/runs/8905804902/job/24457010553?pr=20850 ## Problems There's a few ways this can go wrong: 1. someone adds notes to the wrong file by mistake: up to a reviewer to catch, but we could add active checks for it too (i.e. we could be explicitly enforcing that there should be changes to the _current_ release notes). 1. if a PR has been open for a long time, it might make changes to the `2.22.x.md` file, but only merge in time for `2.23.x`, and thus the release notes are targetting the wrong series. There's a few potential mitigations for this (I think 1 is likely good enough for now): 1. when branching for a new release, the person doing is now told to go and check open PRs for changes to the wrong release notes file and ask the author to update, with a script 2. if merged via a merge queue (e.g. #20193), a CI check for 1 would catch this too 7. this'll make cherry-picking more awkward and fail more often, e.g. if a change has release note in `2.22.x.md` and we cherry pick it to the `2.21.x` branch, that file won't exist and the cherry picker will fail. I think this is probably tolerable for now (at least, worth trying). There's a potential few mitigations (I think the first is the better use of energy): 1. switching to a different approach to notes where they end up in separate dedicated files (see "Future work") 2. making the cherry-picker script more intelligent, e.g. ignore notes or copy them across magically ## Initial roll-out We're early in the 2.22.x dev cycle on `main`. I've whipped up a `2.22.x.md` notes file with everything that's landed before this in #20878, and then future PRs will augment that. Once we branch for 2.22.x and start on 2.23.x we'll just need to make the `2.23.x.md` file then, and keep going as we were. The existing stable branches (2.19.x, 2.20.x, 2.21.x) will continue with the old process, release notes in a batch. ## Future work There's further iteration we can do on this: - We may want to eventually consider a tool like towncrier (as discussed #19247), especially if we're getting a lot of merge conflicts on the release notes files, since that'll aggregate the notes across separate files that don't interact between PRs. - Putting these human-curated notes into the GitHub release announcements, rather than the PR titles. However, for either of those, I think we'll still (conceptually) want enforcement along these lines: a PR needs to either have release notes included (in whatever format we land on), or a human needs to explicitly opt-out. Thus, this is an incremental step that won't be wasted work.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This starts a
2.22.x.mdfor work-in-progress features on themainbranch. This is preparation for #20850: once that's in, we'll be maintaining this file as we go, so it helps to seed it.Currently includes everything up to b75eb07. release_2.21.0a0...b75eb07