#20888 New release notes process: notes in every PR New discussion created by huonw I've now merged #20850, which adds a new CI check: release notes are required. This is a new process that will have us maintain release notes in markdown files in

docs/notes

as we go, so that it's easier: • for users to see a human-curated summary of what's new in the development branches, • for Pants maintainers to do stable releases (and thus we'll be able to do them more often!). Here's my current thinking of the process: • for contributions (i.e. what do when opening a PR) • for reviewing a PR • for doing a release • plus some notes about this transition period Please ask if anything is unclear. Process change is hard! (NB. there's some discussion in #20850 about next steps, including reference to #19247.) For contributions 1. Open a PR as usual 2. You may get a reminder to add release notes. • For some changes, no release notes are required (see below), a Contributor/Maintainer will just need to label the PR appropriately. • For others, they should be added: find the right file in

docs/notes/...

(usually, the biggest number,

2.22.x.md

currently) and add a sentence or a paragraph. 3. If you happen remember in advance, feel free to add release notes before opening the PR. Non-exhaustive examples of changes that don't need release notes: • minor doc improvements • fixes to features that haven't been released yet (although sometimes the release notes for that feature can be updated!) • internal CI changes (covered by being labelled with

category:internal

usually) Use your discretion to decide if something isn't worth calling out, and feel free to ask on the PR or in slack. For reviewing a PR When reviewing a PR, it may have releases notes already, in which case: • review them like any documentation • check they're in the right file: the first 2.x.0 stable release that they'll be released in. For example: • if a PR is just merging to the

main

branch, and it's is leading up to the 2.22 releases (as it is now), release notes should be in

docs/notes/2.22.x

• if a PR will be cherry picked back to 2.21.x (2.21.0 is not yet released), they can go in

docs/notes/2.21.x.md

If it doesn't have release notes, the release notes CI job will fail (unless labelled), and will remind us to either: • add release notes • add a label: •

release-notes:not-required

to opt-out of release notes when not required (see above for a hint) • PRs labelled

category:internal

don't require release notes (but can have them, if required) For doing a release When doing a dev or RC release, nothing has changed. There are changes for other release: • a0: when we do a release like

2.22.0a0

, the

main

branch goes from being for 2.22 to being for 2.23, so release notes need to switch to a new file (by default). #20850 updates the release procedure with what we should be doing here. • stable: release notes are already written, but it's probably worth doing a once-over to check they make sense! For this transition With the transition to a new process, they'll be a bunch of existing PRs that don't have release notes and may not have the new CI check run on them before merging. This means we may have some cool new feature that merges but isn't included in release notes... so no-one knows about it! I (@huonw) have gone through the most likely candidates (PRs approved now) and asked for an update, and I'll keep an eye on what's merged and back-fill the notes if we miss something. pantsbuild/pants