Smarter CHANGELOG management

[davidhewitt]

One of the most common merge conflicts I encounter is our CHANGELOG.

Also, having to annotate the PR number at the end of the CHANGELOG message is a little fiddly. Since discussions were enabled on the repo I keep predicting the PR number incorrectly, leading to typos like #2336 (or just needing to push to correct).

I've seen systems like cpython's NEWS.d where the items are committed seperately and then merge as part of the release process.

Should we consider something similar here? Anyone know of a nice system for Rust?

[messense]

https://github.com/changesets/changesets but in TypeScript, there is a similar project in Rust but it doesn't seem mature enough.

[mtreinish]

I've been using reno for this but it's in python and only has built-in integration with sphinx/rst. The nice thing with it though is that it uses git history to determine which release a release note is part of. (here is an example of the output: https://qiskit.org/documentation/retworkx/release_notes.html from the input: https://github.com/Qiskit/retworkx/tree/stable/0.11/releasenotes/notes/0.11)

[jeertmans]

Hello, maybe you can have a look at git-clif, a git tool written in Rust that can be used to automate CHANGELOG generation. This tool works best with conventional commits (which I don't think you use) but can easily be tweaked to do (almost?) anything you want.

I'm not the author of this tool, but I really enjoy using it and I thought it was worth mentioning it ;-)

[birkenfeld]

Should this be a discussion?

[davidhewitt]

Good idea, moved!

[aganders3]

A number of prominent Python projects use towncrier. The drawback I see is that it wants to tie every change to an issue/ticket number.

Maybe that could be configured to point to the PR number instead? The format is configurable:
https://github.com/twisted/towncrier/blob/f7ab08575de5f3217e9f9d4ae2cf2db7358ec603/pyproject.toml#L5

Edit: the other bummer is that I think it only supports rst.
Edit2: though some people manage to configure it to output markdown: twisted/towncrier#128

[davidhewitt]

Looks like it can work well for us! I've pushed a draft to #2607

[CLOVIS-AI]

If you want to go to low barrier of entry but with a little bit of manual work, here's what I do in other projects:

• Add the changelog sections to each pull request, each collaborator fills them in when creating the PR
• When you create a new release, simply run git log --first-parent --format=%B main, copy all the changelog sections and create a git tag

It can never create conflicts, and the changelog is available offline at any point by listing the tags.