#19247 Proposal: Shift changelog content generation awar from releaser onto PR author New discussion created by thejcannon Proposal In order to help automate the release process, and shift the burden of changelog "news fragments" from the releaser onto the PR author, I propose we shift our process to have the PR which proposes a change also update the changelog. Manually curating the changelog is a breeding ground for merge conflicts, so I suggest we leverage `towncrier` to aid us as well. Towncrier is able to generate changelog entries from in-repo "news fragments" which exist as markdown files on disk with a very short summary of the change. This essentially eliminates

changelog.py

. It is customizable enough to adapt to our current categorizations. * * * How PRs • PR authors, in addition to making code changes (and possibly docs changes) will also add a file whose name is the category (unless it is "internal") with suffix ".md" in a new directory under

src/python/pants/notes

. If the PR requires a cherrypick, the directory will be the name of the milestone (e.g.

2.15.x

) otherwise the directory will be

main

. E.g. #19184 would've added

bugfix.md

to

src/python/pants/notes/main

. #18917 would've added

performance.md

to

src/python/pants/notes/2.15.x

. • CI will validate that the file has been added and matches the category label. It will also validate the directory is correct based on the milestone. • CI will immediately rename the file to include the PR number as the prefix and push to the branch (CI will skip testing). This serves two purposes: • towncrier requires all news fragments start with a unique slug (this avoids merge conflicts). The PR is a unique identifier for the change. • When generating the changelog, this is used to reference the PR which introduced the change. • (Cherry-picking happens normally) • If a cherry-pick is determined to be needed after merging. A new PR should be made that moves the file into the relevant subdirectory from

main

. This PR MUST be cherry-picked, and must be picked after the original cherry-pick is merged. • (This can be automated) Branching • When

main

is bumped to

.a0

, the directory for the feature branch is created (e.g.

2.17.x

), and the relevant

towncrier

configs are added/updated. • Now cherry-pick PRs can target 2.17.x with their docs • Open PRs not label for cherrypick will be using the directory

main

, which will point to the next version when they are released • (This can be automated) Releasing • When preparing a release for a feature-branch, run

towncrier build --config src/python/pants/notes/<branch>/towncrier.toml --version <new version> --date '<human date>'

• (This will be automated) • This will delete the news fragments on disk and update the relevant changelog

.md

. • Make a PR which should be labeled for cherry-pick targeting the right branch • When preparing a

.devN

release, the only differences are: • Use the config for

main

• Don't label for cherry-pick * * * (We can decide after the fact if we want to keep the PR labels, or just use the fragment name. I consider that out of scope for this proposal though. The category labels will continue to be required and must match the filename.) pantsbuild/pants