Drop CHANGELOG.md and generate Changelog automatically

[ccremer]

Context

Currently, we maintain a CHANGELOG.md from https://keepachangelog.com, however the maintenance of this file is (IHMO) a pain:

• It's often outdated
• May not contain all changes since last release, one has to view the git history anyway
• Especially on GitHub, people often expect the changelog in the releases page. There we often find a copy of the CHANGELOG.md, but this is done manually and not even in all cases.
• Often requires "preparation" commits for releases (renaming Unreleased section to next SemVer, search git/PR history whether there are missing changes etc.)

My proposal:

1. Drop the CHANGELOG.md from the repositories, issue templates and other documentation
2. Use a GitHub Action to generate the changelog in the GH Release
   • Uses GH API to extract Titles from PRs and creates nice links
   • PRs can be grouped visibly in the changelog into categories (e.g. Fixes, Features, etc) with GH labels. Or be uncategorized if no labels

Both approaches (keepachangelog) and the generated one from the Action require discipline, but the generated one reduces this discipline to maintain nice PR titles (which we hopefully do already) and setting labels if categorization is required. But even without categorization, it's included in the changelog. More automation, more better :)

Alternatives

Go-based projects can use https://goreleaser.com/ to generate a changelog directly from commits. Other programming languages may or may not have something similar that can be integrated into GH Actions. This proposal is not about dropping Goreleaser or its feature in order to make every Syn-project have the same look of the changelog, but rather enabling automation for those projects that don't have any sort of changelog generation at all.

[tobru]

Relates to #118

[srueg]

I feel exactly the same about the manually maintained CHANGELOG.md solution. Also I never had the use case to look at the changelog on the local disk (which wouldn't be possible with the proposed solution).

So from me it's a clear go for the proposal 👍

[corvus-ch]

I do understand that maintaining a change log is a hassle but for me it is what works best. From all the tools I have looked to automate this, were a disappointment to me. They do lack structure in their output and or require sings to be put in commit messages and or are bound to a specific GIT hosting API (GitHubt, GitLab, Bitbucket etc.).

I would like to be surprised and not have to do this manually.

[ccremer]

We can still alter the release notes after it has been generated if something is not worded appropriately, but at least the manual collection of the changes is automated and we have a good starting point for minor adjustments.

[srueg]

I'd say it's definitely worth to give it a try. Also in my opinion it's not really a requirement to be Git hosting provider independent.

The release-changelog-builder GH action seems simple and extendable enough.

The Kubernetes release notes generator might also be interesting. (See crossplane/crossplane#1828)

[ccremer]

So I played around with the changelog builder, even for a project that uses Goreleaser.

https://github.com/ccremer/k8up/releases
I keep the fork around for a bit, but not too long :)

some other pic with documentation

Config (labels & template) here: https://github.com/ccremer/k8up/blob/v1.1.0/.github/changelog-configuration.json

Please have a look and we can discuss our further steps. But it looks pretty nice :)

[ccremer]

We could further discuss whether the "changes" need to be further separated.
The breaking changes are especially important for users to migrate, but with the same label called "change" this would also include irrelevant changes like "Optimize GitHub workflow" (which are neither features nor bugfixes).
Maybe make a separate label for breaking changes? Is it worth the separation?

[ccremer]

We have gone ahead with K8up already: https://github.com/vshn/k8up/releases/tag/v1.0.0-rc2