search

projectsyn / documentation

The Project Syn main documentation repository
https://docs.syn.tools/
BSD 3-Clause "New" or "Revised" License
6 stars 3 forks source link

Drop CHANGELOG.md and generate Changelog automatically #119

Open ccremer opened 3 years ago

ccremer commented 3 years ago

Context

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

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 commented 3 years ago

Relates to https://github.com/projectsyn/documentation/pull/118

srueg commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 https://github.com/crossplane/crossplane/issues/1828)

ccremer commented 3 years ago

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 :)

image some other pic with documentation image

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 commented 3 years ago

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 commented 3 years ago

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