Automatically create Changelog

[metmajer]

Is your feature request related to a problem? Please describe.
Maintaining Changelogs at release time is a time-consuming task. This could be automated.

Describe the solution you'd like
At terraform-docs, as many other open source projects, we use the git-chglog generator to do just that. A sample config and template can be found here.

FYI @gerardcl

[gerardcl]

@segator was also proposing a tool more integrated to github, let's check that too!

[michaelsauter]

@metmajer Yes! That would be so awesome. Can you explain a little how your process looks like so that git-chglog can generate the changelog well? E.g. how do you deal with labels/milestones/projects? And how do you deal with issues vs. PRs?

[metmajer]

@michaelsauter I thought you'd like it :)

It's really simple. git-chglog looks at your tags and the commit messages therein and generates a CHANGELOG.md file (name can be changed) based on a template (widely used Changelog templates can be generated through the CLI).

Being a git-based tool, git-chglog doesn't know anything about your structure in GitHub, and I am also not sure it should. In a configuration file, you can group your commit messages based on some prefix or regular expressions, so the way you categorize them is entirely up to you. git-chlog's own CHANGELOG.md shows what such a grouping would look like. Changes that have not yet been tagged can be rendered in a group Unreleased.

The tool filters out merge commits and you should also filter out commit messages of kind Bump version to vX.Y.. Especially, of course, when using semantic versioning :-) In order to facilitate releases, I suggest to integrate the Changelog creation into a make changelog, that is also used in a make release target. I am generally fond of creating such abstractions as they come in very handy.

With terraform-docs, we've recently updated our Changelog template to support both unprefixed and prefixed commit messages for grouping, and will make use of prefixes beginning with our upcoming release. In practice, this doesn't mean that every commit has to be properly prefixed, but a feature branch will need to be squashed and prefixed before it gets merged into master.

[michaelsauter]

Hmm, then I am not convinced about the tool.

I strongly feel that a changelog has nothing to do with commits. Commits are IMHO the wrong level for a changelog. There are people that care about commits, and then there are people that do not care about commits. I was in the first camp for a long time before I came to the conclusion that when you work on GitHub with pull requests and such, those are your "units of change", so really that information that is put there should be part of your changelog. If you have a changelog that does not reference the issues I feel it is hard for consumers to decide the impact of the change. For more background on my views, please see https://zachholman.com/posts/git-commit-history/ and https://keepachangelog.com/en/1.0.0/.

The tool I would like to have does this:

• Grab all issues that are assigned to a particular project or milestone.
• Categorize them by tag (bug, enhancement, etc.).
• Add one entry per issue (the title) and link to the issue.

This process implies that: all changes are done through pull requests, and for every PR there must be at least one issue that describes the bug/feature/whatever.

If that tool does not exist yet, it seems time for a new side-project :D

Or you convince me otherwise, but right now I have a pretty set view on how this should work...