Manage the changelog automatically #172

New Issue

2025-11-02T03:12:10-06:00

GiteaMirror commented

2025-11-02 03:12:10 -06:00

Originally created by @tboerger on GitHub (Dec 27, 2016).

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.

Originally created by @tboerger on GitHub (Dec 27, 2016). 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.

GiteaMirror added the type/proposal type/docs labels 2025-11-02 03:12:10 -06:00

GiteaMirror closed this issue

2025-11-02 03:12:10 -06:00

GiteaMirror commented

2025-11-02 03:12:11 -06:00

@bkcsoft commented on GitHub (Dec 27, 2016):

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

@bkcsoft commented on GitHub (Dec 27, 2016): 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, 👍

GiteaMirror commented

2025-11-02 03:12:11 -06:00

@tboerger commented on GitHub (Dec 27, 2016):

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.

@tboerger commented on GitHub (Dec 27, 2016): 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.

GiteaMirror commented

2025-11-02 03:12:11 -06:00

@bkcsoft commented on GitHub (Dec 27, 2016):

(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 ;)

@bkcsoft commented on GitHub (Dec 27, 2016): (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 ;)

GiteaMirror commented

2025-11-02 03:12:11 -06:00

@tboerger commented on GitHub (Dec 27, 2016):

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

@tboerger commented on GitHub (Dec 27, 2016): And I don't like the Gitlab approach to simply dropping the files. You are not easily able to regenerate the changelog.

GiteaMirror commented

2025-11-02 03:12:11 -06:00

@bkcsoft commented on GitHub (Dec 29, 2016):

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

@bkcsoft commented on GitHub (Dec 29, 2016): @tboerger that's easy, just go back in time 😆

GiteaMirror commented

2025-11-02 03:12:12 -06:00

@bkcsoft commented on GitHub (Dec 29, 2016):

but sure, lets keep them in versioned folders :)

@bkcsoft commented on GitHub (Dec 29, 2016): but sure, lets keep them in versioned folders :)

GiteaMirror commented

2025-11-02 03:12:12 -06:00

@bkcsoft commented on GitHub (Dec 29, 2016):

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

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

@bkcsoft commented on GitHub (Dec 29, 2016): > for the filename I would suggest the format `YYYYMMDD-short-title.yml`. I'd prefer `PR#-short-title.yml` :)

GiteaMirror commented

2025-11-02 03:12:12 -06:00

@bkcsoft commented on GitHub (Dec 29, 2016):

write a Go script to scripts/

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

@bkcsoft commented on GitHub (Dec 29, 2016): > write a Go script to scripts/ as in a binary or something you `go run scripts/changelog.go` ? (I'm partial to the latter)

GiteaMirror commented

2025-11-02 03:12:13 -06:00

@lunny commented on GitHub (Dec 30, 2016):

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.

@lunny commented on GitHub (Dec 30, 2016): 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.

GiteaMirror commented

2025-11-02 03:12:13 -06:00

@bkcsoft commented on GitHub (Jan 2, 2017):

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

@bkcsoft commented on GitHub (Jan 2, 2017): @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 :)

GiteaMirror commented

2025-11-02 03:12:13 -06:00

@tboerger commented on GitHub (Jan 16, 2017):

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.

@tboerger commented on GitHub (Jan 16, 2017): > 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.

GiteaMirror commented

2025-11-02 03:12:13 -06:00

@bkcsoft commented on GitHub (Jan 20, 2017):

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 😉

@bkcsoft commented on GitHub (Jan 20, 2017): > 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 😉

GiteaMirror commented

2025-11-02 03:12:14 -06:00

@lunny commented on GitHub (Feb 5, 2017):

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

@lunny commented on GitHub (Feb 5, 2017): Any PR to send for v1.1? Or should I move it to v1.2?

GiteaMirror commented

2025-11-02 03:12:14 -06:00

@bkcsoft commented on GitHub (Mar 17, 2017):

@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...)

@bkcsoft commented on GitHub (Mar 17, 2017): @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...)

GiteaMirror commented

2025-11-02 03:12:14 -06:00