Manage the changelog automatically

[tboerger]

Currently writing the changelog is pretty cumbersome, we should take take the approach of Gitlab to write changelog records in yml format and automatically generate the changelog out of that. Every PR author can write a new yml file into a specific folder so that we can generate the changelog automatically. You can see the records of Gitlab at https://gitlab.com/gitlab-org/gitlab-ce/tree/master/changelogs/unreleased.

Format

I think the format used by Gitlab is already pretty fine, but I would also add a kind flag for grouping:

kind: enhancement # Possible values: breaking, feature, bugfixes, enhancement, misc
title: A short title that explains the change
pull_request: 256
issue: 234
author: tboerger

• kind: Group the changelog records by this flag as we currently got for v1.0.0 release
• title: A possibly short title to explain the change
• pull_request: Optionally the number of the pull request used as a reference
• issue: Optionally the number of the meta issue for multiple pull requests
• author: The name of the author who contributed the change

Directories

For entirely new features I would suggest to put the file into changelog/unreleased, if it's already clear which version will be the target for this change we should put it into changelog/v1.1.0, for the filename I would suggest the format YYYYMMDD-short-title.yml.

Scripting

To generate the changelog I would like to write a Go script to scripts/ that generates the CHANGELOG.md file out of the yml files. We can even integrate this into the CI process and add a commit which includes [skip ci] in the commit message to update this on every merge on master and the release branches.

[bkcsoft]

I don't think we need to bother with changelog/v1.1.0 etc, just seems cumbersome. For backports this will be fixed anyhow with the separate PR.

As for kind I'd like to have security as well, since those have a higher backport priority :)

As for the rest, 👍

[tboerger]

But if you manage the changelog records within version directories you can always regenerate the entire changelog. I'm OK to put everything into unreleased and move that to a version directory directly before the release.

[bkcsoft]

(not saying we should copy them right of but) GitLabs changelog-script removes the old files when it's done, so the versioned ones would be m00t ;)

[tboerger]

And I don't like the Gitlab approach to simply dropping the files. You are not easily able to regenerate the changelog.

[bkcsoft]

@tboerger that's easy, just go back in time 😆

[bkcsoft]

but sure, lets keep them in versioned folders :)

[bkcsoft]

for the filename I would suggest the format YYYYMMDD-short-title.yml.

I'd prefer PR#-short-title.yml :)

[bkcsoft]

write a Go script to scripts/

as in a binary or something you go run scripts/changelog.go ? (I'm partial to the latter)

[lunny]

I think teabot could detect the PR merged and automatically send a PR to add a new changelog to .yml file. If teabot make a bad changelog we can add some commmits to the PR or close this PR. If we need teabot resend a PR. We can give a "RESEND PR". This will reduce many work and not conflict with above.

[bkcsoft]

@lunny the idea is to have it done automagically on any tag-event so having the bot send a PR would be counter-productive in this case :)

[tboerger]

I'd prefer PR#-short-title.yml :)

Than you can add it only after opening the PR.

as in a binary or something you go run scripts/changelog.go ? (I'm partial to the latter)

Use go run and add a ignore build tag.

[bkcsoft]

Than you can add it only after opening the PR.

It usually changes during the course of a PR so it makes sense to add it later on 😉