Better support for change groups in our Keep a Changelog parser & writer

[colincasey]

Our representation of the Keep a Changelog format is compliant with the following Guiding Principles from the spec:

• [x] Changelogs are for humans, not machines.
• [x] There should be an entry for every single version.
• [ ] The same types of changes should be grouped.
• [x] Versions and sections should be linkable.
• [x] The latest version comes first.
• [x] The release date of each version is displayed.
• [x] Mention whether you follow Semantic Versioning.

As noted above, we currently do not parse or validate the "change groups" listed in the spec:

• Added for new features.
• Changed for changes in existing functionality.
• Deprecated for soon-to-be removed features.
• Removed for now removed features.
• Fixed for any bug fixes.
• Security in case of vulnerabilities.

Instead, the content between version entries is simply treated as literal text. This is because we have existing changelogs that aren't in compliance with the spec. For example:

• https://github.com/heroku/buildpacks-jvm/blob/main/buildpacks/jvm/CHANGELOG.md
• https://github.com/heroku/buildpacks-nodejs/blob/main/buildpacks/nodejs-corepack/CHANGELOG.md

We also automatically add an default - No Changes. entry when a version is bumped as part of our fixed versioning strategy and there are no notable changes from the last version. This does not have an easy representation in the spec.

Questions to discuss:

• How should we deal with those existing non-compliant changelogs?
• How should we track the "No Changes" case?

[colincasey]

For "No Changes" I wonder if we should follow similar guidance for yanked releases given in the FAQ:

Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions don't even appear in change logs. They should. This is how you should display them:

## [0.0.5] - 2014-12-13 [YANKED]

The [YANKED] tag is loud for a reason. It's important for people to notice it. Since it's surrounded by brackets it's also easier to parse programmatically.

We could do something similar for releases with no changes and use ## [0.0.5] - 2014-12-13 [NO CHANGES]. This would make it easier to enforce parsing of the version entry content since it would avoid having to deal with both changelog groups & the "No Changes" special case.

[Malax]

How should we deal with those existing non-compliant changelogs?

By fixing them. We have full control over them and if they are not compliant to the spec they're supposed to follow they are wrong and need fixing (regardless of the release automation). I created an issue for the JVM one: https://github.com/heroku/buildpacks-jvm/issues/595

[edmorley]

I've fixed Go's changelog in https://github.com/heroku/buildpacks-go/pull/172.

[Malax]

The JVM changelogs should now be in order as soon as https://github.com/heroku/buildpacks-jvm/pull/716 is merged. Do we have further blockers?

[colincasey]

Yes, but I'm not sure how many are non-compliant. So to move this issue along without breaking anyone for release automation I think we'd first need:

• A shared changelog validator GitHub action added to this repo (similar to our changelog modification action)
• The above validation action wired up in each CNB project
• Also, there is a bug in https://github.com/heroku/keep_a_changelog_file that sometimes silently drops invalid markdown items instead of failing

I've been meaning to look into those but just haven't had the time 😞

[edmorley]

Perhaps to avoid the overhead of another shared action and having to add it everywhere, we could start with having the prepare-release workflow run some checks and output warnings (the kind that get shown on the checks overview)?

[colincasey]

Yeah, that's a reasonable alternative. As long as we can surface changelog issues without blocking releases for now. We can enable stricter enforcement later on.