Improve changelog

[beatngu13]

We currently use the shipkit-changelog Gradle plugin to generate changelogs for releases. For example, this is the generated changelog for v1.7.0:

1.7.0

• 2022-04-10 - 10 commit(s) by Daniel Kraus, Filip Hrisafov, Marcono1234, Matthias Bünger, Mihály Verhás, Nicolai Parlog
• Fix Java version for release job (#620)
• Remove CLA (#616)
• Inherit default locale and timezone annotations (#615)
• Update JUnit to 5.8 (Update JUnit to 5.8 #594 / Update JUnit to 5.8 (#594 / #612) #612) (#612)
• Update to JDK 11 (#608)
• Update JDK used for builds (#606)
• Add name attribute for @RetryingTest (#601)
• Update JUnit to 5.8 (#594)
• Add CLA-Bot (#591)
• Fix most compiler warnings (#565)
• Align use of extension point (#496)
• Support JSON as source for parametrized tests arguments (#492)
• Enclosing classes vs Before/AfterAll (#479)
• Support JSON as source for parameterized tests arguments (#101)
• Replace Upstream Test Code With Dependency (#6)

As can be seen, and as described in the plugin's readme, the generated "[…] changelog [is] based on commit history and Github pull requests/issues".

In contrast to other changelog generators such as release-drafter or GitHub native, there seem to be little to no configuration options? Something I consider a problem is, e.g., the missing ability to filter tags like theme: build, as this can be confusing to users. For example, the changelog entry "Update to JDK 11 (#608)" let this user think v1.7.0 can only be used with Java 11+.

We should (i) discuss how we can improve our changelog and (ii) if such improvements can be done with shipkit-changelog, or if we require other tooling.

[beatngu13]

Here's an example for GitHub's native generator, which I set up for the gluonfx-maven-plugin:

• Configuration: https://github.com/gluonhq/gluonfx-maven-plugin/blob/master/.github/release.yml
• Generated changelog: https://github.com/gluonhq/gluonfx-maven-plugin/releases/tag/1.0.13

[Bukama]

I like customizeable changelogs :)

[nipafx]

I think this is a good idea, go for it!

[Michael1993]

I had a lame idea that I think is worth considering: keeping a manual changelog.

I can already hear the masses gasping in terror, "manually doing a task that could be automated?!", but yes, I've seen projects do this and it always makes for a nice, clean and easy-to-digest changelog. It adds a little bit of work for each PR author (or maintainer) but it's fairly minimal and it provides a degree of control that no other solution can offer.

[beatngu13]

I did use "Keep a Changelog" in some other projects and we (me and my teammates) often forgot to update the CHANGELOG.md. It also caused merge conflicts sometimes.

I believe it is easier for us to leverage our already nice PR titles/descriptions and labels, and generate the changelog. We already have type: new feature and type: bug for categorizing the changelog entries, but we would need at least one more label to opt-out a change from the changelog.

PS: GitHub can now render mathematical expressions, so I do this (because I can):

$e^{\pi i} + 1 = 0$

See also: Euler's identity

[nipafx]

I agree with both of you. 😁 It seems overkill to try and automate this in detail (which label combinations, exactly?) but a manual log is error-prone as well.

What if we try better automation as @beatngu13 proposes, but don't try to hit the nail right on the head with what exact issues are included (because I assume that'll be complex and also prone to then-automated errors). Instead, following a release, we go over the release notes manually and kick out what doesn't belong there?

[nipafx]

@beatngu13 : Please let me know if you will work on this in the near future. If not, I might kick it out of the 2.0 milestone to get that one closer to the finishing line.

[beatngu13]

@nipafx I don't think I will find time soon. I will remove it from the milestone, so it doesn't block our progress towards 2.0.

[nipafx]

Just for fun, after releasing 1.7.2, I went into the generated changelog and filtered out the more user-facing issues/PRs (it's a bit weird that we include both) and placed them on top under the heading "Prominent changes". That was pretty quick, so I think it's doable.

We should really look into including issues and PRs, though - feels to me that just one (probably issues?) would suffice.