Manage the changelog automatically #505

New Issue

lunny · 2016-12-27T12:51:10Z

tboerger commented

2016-12-27 12:51:10 +00:00

(Migrated from github.com)

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.

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/40421711-manage-the-changelog-automatically?utm_campaign=plugin&utm_content=tracker%2F47456670&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F47456670&utm_medium=issues&utm_source=github).

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. <bountysource-plugin> --- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/40421711-manage-the-changelog-automatically?utm_campaign=plugin&utm_content=tracker%2F47456670&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F47456670&utm_medium=issues&utm_source=github). </bountysource-plugin>

👍 2

bkcsoft commented

2016-12-27 13:33:21 +00:00

(Migrated from github.com)

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, ?

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 commented

2016-12-27 13:36:33 +00:00

(Migrated from github.com)

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 commented

2016-12-27 13:45:37 +00:00

(Migrated from github.com)

(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 commented

2016-12-27 21:40:09 +00:00

(Migrated from github.com)

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

bkcsoft commented

2016-12-29 21:16:22 +00:00

(Migrated from github.com)

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

bkcsoft commented

2016-12-29 21:16:41 +00:00

(Migrated from github.com)

but sure, lets keep them in versioned folders :)

bkcsoft commented

2016-12-29 21:17:55 +00:00

(Migrated from github.com)

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

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

> for the filename I would suggest the format `YYYYMMDD-short-title.yml`. I'd prefer `PR#-short-title.yml` :)

bkcsoft commented

2016-12-29 21:18:49 +00:00

(Migrated from github.com)

write a Go script to scripts/

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

> 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 commented

2016-12-30 00:35:44 +00:00

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 commented

2017-01-02 21:08:02 +00:00

(Migrated from github.com)

@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 commented

2017-01-16 22:38:27 +00:00

(Migrated from github.com)

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.

> 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 commented

2017-01-20 07:49:03 +00:00

(Migrated from github.com)

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 ?

> 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 ?

lunny commented

2017-02-05 14:22:38 +00:00

Any PR to send for v1.1? Or should I move it to v1.2?

bkcsoft commented

2017-03-17 04:11:38 +00:00

(Migrated from github.com)

@tboerger I'm currently working on this, saw this one

Than you can add it only after opening the PR.

But your spec includes the PR-number as well :trollface: (I still wanna enforce PR-number on files to avoid collisions...)

@tboerger I'm currently working on this, saw this one > Than you can add it only after opening the PR. But your spec includes the PR-number as well :trollface: (I still wanna enforce PR-number on files to avoid collisions...)

This repo is archived. You cannot comment on issues.