Proposal to improve changelog handling

[bugadani]

Currently, the keeping changelogs causes some minor, but nontrivial friction:

• Even trivial changes require a changelog entry, unless maintainers tell otherwise with a label
• Keeping the changelog requires knowing the PR number up front
• The responsibility to add entries is on the contributor
• Multiple PRs can end up conflicting on the changelog only, which reduces the efficiency of the merge queue if a PR gets rejected partway through the process

My proposal is to stop tracking the changelog and the migration guide additions in tree. Instead, we should add some markup to the PR description, where we, the maintainers (or the more advanced contributors, but only optionally) can propose the changelog entry/migration guide addition.

The xtask can, in the release planning phase, collect these PR descriptions, extract the data and modify the changelogs/migration guides.

The exact syntax of the PR description is subject to bikeshedding. The format should be rich enough to be unambiguous, contain which crate(s) are changed and how, and optionally which area in a crate has been changed (for example, a peripheral like SPI/RMT could be one such area). If we get the format right, the PR descriptions may be informative enough without much additional comment. As an initial idea, I propose we just use markdown syntax with a slightly restricted format:

## Change: esp-hal/LOL-area

- Added: FOO
- Changed: BAR
- Removed: BAZ

## Change: esp-radio

- Changed: Public API changes related to LOL-area

## Migration: esp-hal/LOL-area

Lorem ipsum with diff

## Migration: esp-radio

Lorem ipsum

I propose we make it clear that keeping the changelog is not the responsibility of the contributor, but we appreciate them keeping to this format. We can easily edit the PR descriptions ourselves, instead of going back-and-forth with contributors on typos/stylistic issues.

To implement this idea, we need:

• First, discuss the approach, and come up with a finalized design.
• A CI workflow that checks for changelog entries in the PR description only if the PR description contains changelog-looking headings. Changelogs are optional, but their format is a bit rigid, so we need to make sure the tooling can cope.
• A CI check that turns direct changelog edits into errors, and comments on the PR how we expect (or expect not to) keep the changelog.
• The xtask needs additional code to collect the changelog entries and turn them into documentation.
• The release process needs to change to allow for manual fine-tuning of the changelog documentation.
• The release process needs to either be able to retrieve the PR description at the time of the merge, or allow for misformatted PR descriptions, as they can be edited at any time.

The advantages are:

• No more merge conflicts
• No more wasted time on updating the PR number in the changelog after the PR has been opened
• Contributors will no longer try to reference issue numbers in the changelog
• We can create a changelog that is grouped by the area, i.e. we will group SPI-related changes together by default
• We can edit the changelog ourselves, which means the end result should be more cohesive.

I'm looking forward for thoughts, opinions, general feedback and everything else that is constructive on this matter.

[bjoernQ]

Interesting idea

Just for my understanding: we will keep the CHANGELOG.md etc. files but the xtask will "maintain" them? Or do you plan to store them somewhere else?

[bugadani]

I did not think about that, I assumed we would keep the markdowns. However, since we're posting the notes on github releases as well, we can probably remove these from the tree completely. I'm undecided, and I think this question is an (important) implementation detail that we can make a decision about at any time.

[bjoernQ]

To me anything that resolves

• merge conflicts
• wasted time on updating the PR number in the changelog after the PR has been opened

sounds like a great thing to have!

One thing that came to my mind is, that we also need to apply that for backport branches / releases. Not sure if it will be a no-brainer and needs special consideration at all. (with the current process we get them "for free": https://github.com/esp-rs/esp-hal/blob/esp-hal-1.0.x/esp-hal/CHANGELOG.md )

One potential drawback might be that we don't have a very easy way to see what is already there for the upcoming release (i.e. we and the community can just have a look at CHANGELOG.md - for sure solvable ... just mentioning)