Auto-generating the CHANGELOG and Migration Guide #2761

joelanford · 2020-04-01T20:58:52Z

Description of the change:
Add template, examples, and prototype generator program to auto-generate CHANGELOG and migration guide.

Motivation for the change:
Too often, we run into merge conflicts because multiple PRs are updating the CHANGELOG in the same area at the same time.

With this PR (or something like it), we would add separate fragment files for each PR that would be much less likely to conflict. Then we would generate the CHANGELOG and migration guide from these files.

Another benefit of this approach is that we can standardize formatting and policy (e.g. breaking changes require a migration guide section)

Tasks:

Sanity check: On every PR, validate every fragment without making filesystem changes
Sanity check: Forbid CHANGELOG and migration guide changes if version.Version ends with "+git"?
Link check: On every PR, run generator and verify links are valid with latest fragments

jmrodri · 2020-04-01T21:05:56Z

from a users POV, is the idea we copy the template to a new file and that becomes our changelog entry?

jmrodri · 2020-04-01T21:07:22Z

depending on what has to be done, I'm lazy enough to add a Makefile target: make changelog that will do the boring stuff and print out the file location for me to fill in.

jmrodri · 2020-04-01T21:08:11Z

depending on what has to be done, I'm lazy enough to add a Makefile target: make changelog that will do the boring stuff and print out the file location for me to fill in. I assume the generate tool is to run in travis right?

joelanford · 2020-04-01T21:08:44Z

The idea is that we run generate.go which will:

read the fragment files to build a new section of the CHANGELOG and migration guide for the entire release
read in the existing CHANGELOG
Write the new section, followed by the existing section to construct the new CHANGELOG

It would be a similar process for the migration guide, but that isn't in the generate.go program yet.

joelanford · 2020-04-01T21:11:05Z

Yeah, we would want to integrate it into the release process somehow. As is, it requires a -title flag to be passed, which would generally be the tag we're about to create/release.

So we would have to do TITLE=v0.18.0 make changelog or something.

joelanford · 2020-04-01T21:27:32Z

Also, from a contributor's point of view, there would no longer be updates directly to CHANGELOG.md. Instead, every PR with a user-facing change would create a new file in /changelog/fragments (based on 00-template.yaml) just for that PR.

This is the change that would help avoid the CHANGELOG.md merge conflicts that we see pretty often. Every time we have to resolve these conflicts requires another run of CI, so this would be a big time-saver for contributors and would help PRs merge faster.

jmrodri · 2020-04-01T21:43:02Z

@joelanford today we have marker checking all of the docs including the CHANGELOG. Presumably with the fragments this might no longer work. Do we still need that type of functionality? Would that just be another part of the release? Or a longer running job that runs nightly and files github issues with broken links. I prefer this option honestly :)

joelanford · 2020-04-01T21:52:34Z

@joelanford today we have marker checking all of the docs including the CHANGELOG. Presumably with the fragments this might no longer work. Do we still need that type of functionality? Would that just be another part of the release? Or a longer running job that runs nightly and files github issues with broken links. I prefer this option honestly :)

I thought about that too. I think as part of the sanity test in every PR, we would re-generate the CHANGELOG and migration guides without consuming the fragments and without committing the regenerated files, and then run marker after that.

That way we can allow markdown in the fragments AND still test that the links are valid.

changelog/fragments/00-template.yaml

joelanford · 2020-04-02T16:12:16Z

changelog/generate.go

+	for _, e := range c.Entries {
+		if e.Migration != nil {
+			haveMigrations = true
+			bb.WriteString(fmt.Sprintf("### %s\n\n", e.Migration.Header))
+			bb.WriteString(fmt.Sprintf("%s\n\n", strings.Trim(e.Migration.Body, "\n")))
+			bb.WriteString(fmt.Sprintf("See %s for more details.\n\n", e.PullRequestLink()))
+		}
+	}


Do we want to arrange these under headers based on kind like we do in the CHANGELOG? Or just flatten the migration entries out and list them one-by-one in the order they're read from the files.

On a separate but related note, do we want to do any sorting of CHANGELOG and migration guide entries?

Do we do any sorting of the migration guide now? I've just always added stuff at the end anyway. Though we may want to consider putting the migration guide into version specific upgrade guides when we build, since I think it's starting to get a bit unwieldy. Might be out of scope although if we do want to go that way may be better to do it now than have to rework the tooling later

Do we do any sorting of the migration guide now?

No, but depending on how we name the fragment files, entries will show up semi-randomly, just based on a lexicographical sort of the filenames.

Though we may want to consider putting the migration guide into version specific upgrade guides when we build, since I think it's starting to get a bit unwieldy.

Yeah I had the same thought. Scrolling to the bottom of a very long migration guide is not the best UX. We could at least reverse the order so that new migration steps are always at the top.

yeah, but if you're two or three versions behind then you need to go to the middle of the document somewhere to find your upgrade instructions, which I think is still just a worse experience than seeing migration_guide-v0.16.md or whatever naming scheme we'd use

I'm good with this change. And it actually makes the generation simpler since there's no need to deal with an existing file.

Migration guides will now be generated in a separate file for each release. In a follow-up, we can split the existing migration guide into separate files per release.

…ELOG and migration guide (operator-framework#2761)

hack/generate/changelog/gen-changelog.go

…ELOG and migration guide (operator-framework#2761)

…nerate migration guide update

…names

changelog/fragments/example1.yaml

estroz

A few nits, otherwise LGTM.

hack/generate/changelog/gen-changelog.go

…ation guide

estroz

/lgtm

openshift-ci-robot · 2020-04-14T03:36:49Z

New changes are detected. LGTM label has been removed.

jmrodri

no additional comments from me. Looking forward to this.

joelanford · 2020-04-16T01:55:14Z

/cherry-pick v0.17.x

openshift-cherrypick-robot · 2020-04-16T01:55:23Z

@joelanford: new pull request created: #2849

Details

In response to this:

/cherry-pick v0.17.x

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

…ELOG and migration guide (operator-framework#2761)

openshift-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 1, 2020

openshift-ci-robot requested review from camilamacedo86 and fabianvf April 1, 2020 20:58

joelanford force-pushed the autogen-changelog branch from 5dcc127 to f564ea4 Compare April 1, 2020 21:12

fabianvf reviewed Apr 2, 2020

View reviewed changes

changelog/fragments/00-template.yaml Outdated Show resolved Hide resolved

joelanford commented Apr 2, 2020

View reviewed changes

joelanford added a commit to joelanford/operator-sdk that referenced this pull request Apr 2, 2020

WIP: templates, examples, and prototype code for autogenerating CHANG…

6fd356e

…ELOG and migration guide (operator-framework#2761)

joelanford force-pushed the autogen-changelog branch 2 times, most recently from aaaf7fd to c4ad017 Compare April 2, 2020 22:51

joelanford added a commit to joelanford/operator-sdk that referenced this pull request Apr 6, 2020

WIP: templates, examples, and prototype code for autogenerating CHANG…

56bd616

…ELOG and migration guide (operator-framework#2761)

joelanford force-pushed the autogen-changelog branch from e1f1122 to 844d0ff Compare April 6, 2020 21:20

joelanford changed the title ~~WIP: Auto-generating the CHANGELOG and Migration Guide~~ Auto-generating the CHANGELOG and Migration Guide Apr 6, 2020

joelanford changed the title ~~Auto-generating the CHANGELOG and Migration Guide~~ [WIP] Auto-generating the CHANGELOG and Migration Guide Apr 7, 2020

openshift-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 7, 2020

asmacdo reviewed Apr 8, 2020

View reviewed changes

hack/generate/changelog/gen-changelog.go Outdated Show resolved Hide resolved

joelanford marked this pull request as ready for review April 8, 2020 20:14

joelanford changed the title ~~[WIP] Auto-generating the CHANGELOG and Migration Guide~~ Auto-generating the CHANGELOG and Migration Guide Apr 8, 2020

openshift-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Apr 8, 2020

joelanford added 4 commits April 8, 2020 16:16

WIP: templates, examples, and prototype code for autogenerating CHANG…

d297dcf

…ELOG and migration guide (operator-framework#2761)

change migration title to header, split things out into functions, ge…

fc65972

…nerate migration guide update

unexport types and functions

d033d20

rename fragments/example.yaml to ensure PR discovery works through re…

a541f3b

…names

joelanford added 2 commits April 8, 2020 16:16

copy release doc changes to ./website

b375ad5

add validate-only flag

b39497c

joelanford force-pushed the autogen-changelog branch from f2ce1c5 to b39497c Compare April 8, 2020 20:16

openshift-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Apr 8, 2020

estroz reviewed Apr 8, 2020

View reviewed changes

changelog/fragments/example1.yaml Outdated Show resolved Hide resolved

estroz reviewed Apr 8, 2020

View reviewed changes

joelanford added 7 commits April 9, 2020 13:51

updated based on PR reviews

966c1a8

separate into library, use Go templates

54cb58f

unexport ToChangelogEntry

6bbb65d

hack/generate/changelog: unit tests for changelog generation

808631e

hach/generate/changelog: add unit tests for fragment parsing and migr…

86feeb3

…ation guide

fix sanity test checks

90e8c97

Makefile: include ./hack in unit tests

fa9f9f8

estroz approved these changes Apr 14, 2020

View reviewed changes

openshift-ci-robot assigned estroz Apr 14, 2020

openshift-ci-robot added the lgtm Indicates that a PR is ready to be merged. label Apr 14, 2020

goimports picked the wrong log package :)

afb26e6

openshift-ci-robot removed the lgtm Indicates that a PR is ready to be merged. label Apr 14, 2020

fix order of imports

a7d79dc

jmccormick2001 approved these changes Apr 14, 2020

View reviewed changes

jmrodri approved these changes Apr 14, 2020

View reviewed changes

joelanford merged commit 19d0e1e into operator-framework:master Apr 16, 2020

joelanford deleted the autogen-changelog branch April 16, 2020 01:55

openshift-cherrypick-robot mentioned this pull request Apr 16, 2020

[v0.17.x] Auto-generating the CHANGELOG and Migration Guide #2849

Merged

openshift-cherrypick-robot pushed a commit to openshift-cherrypick-robot/operator-sdk that referenced this pull request Apr 16, 2020

WIP: templates, examples, and prototype code for autogenerating CHANG…

326e067

…ELOG and migration guide (operator-framework#2761)

joelanford mentioned this pull request Apr 16, 2020

Makefile: fix script paths for 'gen-*' make targets #2850

Merged

jmrodri mentioned this pull request May 8, 2020

Add guidelines on PR + commit text openshift/enhancements#311

Merged

Auto-generating the CHANGELOG and Migration Guide #2761

Auto-generating the CHANGELOG and Migration Guide #2761

Uh oh!

Conversation

joelanford commented Apr 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jmrodri commented Apr 1, 2020

Uh oh!

jmrodri commented Apr 1, 2020

Uh oh!

jmrodri commented Apr 1, 2020

Uh oh!

joelanford commented Apr 1, 2020

Uh oh!

joelanford commented Apr 1, 2020

Uh oh!

joelanford commented Apr 1, 2020

Uh oh!

jmrodri commented Apr 1, 2020

Uh oh!

joelanford commented Apr 1, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

joelanford Apr 2, 2020

Choose a reason for hiding this comment

Uh oh!

fabianvf Apr 2, 2020

Choose a reason for hiding this comment

Uh oh!

joelanford Apr 2, 2020

Choose a reason for hiding this comment

Uh oh!

fabianvf Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

joelanford Apr 3, 2020

Choose a reason for hiding this comment

Uh oh!

joelanford Apr 14, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

estroz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

estroz left a comment

Choose a reason for hiding this comment

Uh oh!

openshift-ci-robot commented Apr 14, 2020

Uh oh!

jmrodri left a comment

Choose a reason for hiding this comment

Uh oh!

joelanford commented Apr 16, 2020

Uh oh!

openshift-cherrypick-robot commented Apr 16, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

8 participants

joelanford commented Apr 1, 2020 •

edited

Loading

joelanford commented Apr 1, 2020 •

edited

Loading