Changelogs for releases

[tautschnig]

It would be very helpful for users to maintain a changelog that lists user-facing differences between releases. We used to have a changelog, but didn't do a good job of maintaining it and removed it in #6019. Since we now have an established release workflow, it would be great to improve it by adding a step to produce a curated changelog from the git history.

[rod-chapman]

As a "user", I would really like to know what's changed with every release... new features, defects corrected etc.
This can just be a new "chapter" or "page" of the documentation that gets updated with every PR (at least... updating that page should be considered as part of every PR, at the discretion the reviewer....)

[TGWDB]

I'm going to turn this into something of an RFC (and add that label) and see if we can reach some agreement on how to proceed. There are a couple of options (and I'm open to more suggestions):

1. Reinstate the old changelog, which requires either:
   A. Updating the changelog with each PR (and reviewers to enforce this before allowing a merge), or
   B. Adding changelog curation to the release process (which adds time/cost/complexity).
2. Enforcing PR title to be suitable for release notes and using some automated method to extract/create a changelog. Note that Github has an option to do this in the manual release process, so maybe it's also available in the workflow?
3. Some other option/approach.

[tautschnig]

I think 1.A. might sometimes be hard to get right, and I'd much favour proper curation at the time of a release. The changelog needs proper editing (just like documentation, but that's a way bigger task left to tackle) and not piece-by-piece tweaking. So I'd suggest a combination of 1.B. and 2. In Kani, we use GitHub's manual release process to create draft release notes, then copy&edit them when pasting them into the changelog file. (And we then discard the draft release before creating a proper release where we copy back the release notes from the changelog file.)

[tautschnig]

Note that the approach taken in Kani actually gives reviewers a chance to comment on the changelog. Take model-checking/kani#2783, where there was considerable feedback on the changelog.

[TGWDB]

I propose to see how this would look for the next release with the following approach:

1. Release PR raised earlier with CHANGELOG built from PR titles (using Github's tool manually).
2. A day or so for reviews (and manual intervention when more things are merged during this window).
3. Release then follows usual path.
   Let's see how much overhead this introduces and whether there is anything that seems difficult to maintain.

[tautschnig]

Is was about to close this as the changelog is now being populated, but then noticed that our GitHub releases page does not actually provide this information, but instead has the always-almost-the-same (except for version numbers) installation instructions. I believe that's the last bit that needs ironing out.

[rod-chapman]

Yes please... in addition to generating the changelog, make sure it gets published somewhere that's really really obvious to users. Appearing on the "Releases" page would be a good start. Can it also be built into the on-line manual?