Make it easier to manage release notes

[llucax]

It was noted by @stefan-brus-frequenz and @tiyash-basu-frequenz that writing release notes, and specially preparing release notes before a release is time consuming and complicated. For bigger projects with a lot of changes and a big audience, like the SDK, having detailed release notes make sense, or at least is worth the effort, but for smaller and more niche projects like the APIs, it might not.

Having release notes in a file have some other issues too:

1. Usually it requires reviewing and updating before a release, which also usually implies a PR, which in turn can significantly slow down the release process.
2. It requires cleaning up after a release (this can be automated)
3. It's prone to have conflicts when multiple PRs update the release notes.
4. It is easy to forget to update release notes in PRs.

It would be good to come up with a better process.

Please reply in the different proposal replies if you have comments on a particular proposal, write a new comment if you have a new proposal, and if you have general comments, like if you prefer one proposal over the other, reply to the General comments comment.

[llucax]

Proposal 1: GitHub changelog

One proposed solution is to just use the automatically generated changelog that GitHub can produce for release. This basically adds a list of PRs merged in that release.

Pros:

• Super lightweight and automated.

Cons:

• No clear instructions for upgrading.
• Not targeted to users, a lot of noise can be included (like changes in the CI, etc.).
• No clear indication of what is a bug fix, what a new feature, what a breaking change (so users will have a hard time to know which changes are relevant to them).
• No customization possible (except maybe if editing the release after-the-fact manually in GitHub, but this won't be updated in release announcements; or maybe extracting the tag commit message and use it as release notes).

For small projects with small audiences this might be an option, but for other projects I think it is not good enough.

[llucax]

I would definitely give this config a shot with the API repos. Still IMHO is not suitable for a project with a big audience, as it transfer all the work of writing good release notes from developers to users but for smaller niche projects it looks pretty decent!

[tiyash-basu-frequenz]

This looks nice. I'd also like giving it a shot.

[tiyash-basu-frequenz]

Still IMHO is not suitable for a project with a big audience, as it transfer all the work of writing good release notes from developers to users

Not sure I understand.
"Users" refers to contributors? If so, then shouldn't contributors be responsible for adding release notes for the part they work on?

[llucax]

Yeah, sorry, that was poorly worded. What I mean is that with the auto-generated release notes, the user will still need to jump to every individual issue/PR to know exactly what changed and how to update their code when needed. So is not like the users will need to write release notes, I was trying to say that the effort that is saved from the developers to actually write release notes will be transferred to the users that now will have a harder time navigating the changelog/release notes, is not that that effort disappears. Hope it is more clear now.

[llucax]

This looks nice. I'd also like giving it a shot.

Do you want to try it out with the microgrid API (if there are any changes coming up, otherwise it might be better to try it out in an API project with more changes coming up soon).

[llucax]

Proposal 2: Minimal change to release notes

@tiyash-basu-frequenz proposed some minimal changes to the the release notes template to minimize the impact of 1 (no summary needs to be created or removed if it is not provided, no sections need to be removed if empty):

# Release Notes

## Upgrading

None

## New Features

None

## Bug Fixes

None

We can still include a summary just below the # Releae Notes if needed.

[llucax]

Proposal 3: Tool to extract release notes from PRs

A more complicated solution to address all of the above would be to write a tool that will gather information from PRs to build the release notes. Some ideas on how this could be implemented:

• Use a PR template to include a changelog entry as part of the PR description. This way people creating PRs will be less likely to forget to add release notes.
• Extract the changelog entry from all PRs as part of the automated release process.
• Extract which type of change is it from labels (bug, enhancement, add a breaking label?)

Cons:

• Hard to customize: it would be hard to offer an opportunity to write a summary or write more cohesive release notes, sometimes is much better to pack different changes into just one release notes item because they are too related for example.
• High effort to implement it.

[llucax]

General comments

[llucax]

IMHO proposal 3 is way too much effort, at least for now.

So I would go either with just proposal 2, or with allowing projects to just go for proposal 1. I guess proposal 2 makes sense for any project, the release notes looks just a little bit funnier if there are empty sections, but it's not the end of the world.

[llucax]

I think the worst problem at the moment is needing to edit the release notes before a release. To solve that we could use the idea of using the tag commit message as the final release notes, and only using the RELEASE_NOTES.md file as a scracthpad.

The only problem with this is the release notes file in the tag will be confusing if someone reads them from the repo, as they not be the final notes. If we wanted to remove them before a release, then we again need a PR before completing a release, which is really annoying.