better changelog / release note management ?

[Simon Michael]

Cc'ing this here too (from #fossmaintainers:matrix.org, #hledger:matrix.org, #hledger:libera.chat ...)

I'm editing the changelogs and it's always a pain. I have automated it a little. hledger's changelogs (and then release notes) are based on commit messages. `./Shake changelogs` does some useful initial content gathering (https://github.com/simonmichael/hledger/blob/master/Shake.hs#L631). I can run it repeatedly to incrementally add interesting commit messages to the proper CHANGES.md files in the right format. This is a great start but the final editing and historical research is still too much. It feels inefficient.

I use a homegrown process not unlike https://www.conventionalcommits.org . Possibly we could take more from there.  

Problem 1: Without good clear changelog-ready commit messages, it's a lot of work to reconstruct the context and clean them up at release time, since a lot of time has passed. 

We try to reference issues in commits, but fairly often it's missed. Yesterday I had to find the context by searching for commit hashes on github several times, I'm wondering about automating that. Then I've got to digest the issue, which often takes a bit of effort; but at least it's detailed.

Problem 2: Getting changelog-ready commit messages is a lot/probably too much to ask of most contributors. Many hledger contributors are first time or infrequent. I feel that adding this to the things I ask of them will just drive many of them away. 

I could add messages myself at merge time if using squash merges, or regular merges. But not when using rebase merges (our common case), unless I alter contributors' commits, which seems awkward.

The ideal would be to stay on top of this throughout the release cycle. Eg, every merge is required to include a good changelog entry. Or, changelogs are updated and brought to release readiness weekly.

hledger's docs are quite important to me and I'm heavily involved in producing them. But if the right person wanted to serve as changelog tsar, that could be another way. (Throw more human power at the problem.) Even so, I think some automation is almost a necessity to produce good results.

Do you know projects that have a good process for this ? I know of Emacs (I think they require contributions to come with finished changelog entry) and https://docs.syncthing.net/dev/release-creation.html?highlight=release#release-candidates-write-a-change-log.

[Alejandro García Montoro]

Hi!

Do you know projects that have a good process for this ? I know of Emacs (I think they require contributions to come with finished changelog entry) and https://docs.syncthing.net/dev/release-creation.html?highlight=release#release-candidates-write-a-change-log.

Not sure if this is too involved for your purposes, and it still puts some burden on the contributors, but just some food for thought.

At Mattermost we use a special code block in every PR that looks like this:

```release-note

Added feature X, Y and Z.

```

The PRs are automatically labeled by a bot with do-not-merge/release-note-label-needed if they do not contain a release note. If they do, they are labeled as release-note, and if the contents of the release-note block are simply "NONE", the PR is labeled with release-note-none. The bot we use for automating this is https://github.com/mattermost/chewbacca.

At the time of release, the marked PRs are parsed with this tool from Kubernetes, https://github.com/kubernetes/release/tree/master/cmd/release-notes, and the release notes are generated.

I don't know more details about the installation and whether it fits hledger use case, but if you're interested, I can ask the guy who owns this at Mattermost.

[Simon Michael]

On Jul 1, 2021, at 12:09 AM, Alejandro García Montoro <alejandro.g...@gmail.com> wrote:

Hi!

Do you know projects that have a good process for this ? I know of Emacs (I think they require contributions to come with finished changelog entry) and https://docs.syncthing.net/dev/release-creation.html?highlight=release#release-candidates-write-a-change-log.

Not sure if this is too involved for your purposes, and it still puts some burden on the contributors, but just some food for thought.

Thanks Alejandro, it's interesting.

All: here's a proposed new set of conventions I will be trying to follow from now on - let's see how it works out, feedback and improvements welcome.

https://hledger.org/CONTRIBUTING.html#commit-messages