doc: write release notes in the same CL as the code change

[andybons]

A change that is considered release-notes worthy has RELNOTE=yes added as a comment. x/build/cmd/relnote then uses these tags to construct the skeleton html doc that eventually becomes the release notes (e.g. https://golang.org/doc/go1.10).

As the release approaches, the burden of writing the release notes then lands on a smaller subset of the team that may not have full context on a change.

I propose that if a change should be considered release-notes worthy, instead of RELNOTE=yes, the release notes doc is updated along with the change to the code.

• The author of the change and reviewers have the most context and can adequately add an item to the release notes while the change is still fresh in their minds
• If the change gets reverted, the change to the release notes also gets reverted as well. No need to keep them in sync separately
• As the release approaches, the amount that needs to be done by the release team is reduced to evaluating API changes, proof-reading, and adding in the remaining pieces

Am I missing anything, here? What advantages do we gain from waiting until near release-time to construct the notes? Do they outweigh the advantages outlined above?

@ianlancetaylor @bradfitz @bcmills @FiloSottile

[bradfitz]

I'm fine with this, as long as everybody realizes it's not a 100% solution. Writing nice release notes does require some human attention to arrange things in a nice order, write some prose that connects sections nicely, and to make things consistent.

I don't want to just parse out some stuff out and concatenate it all together and ship it.

For example, look at https://kubernetes.io/docs/imported/release/notes/#general-fixes-and-reliability ... the bullets are a mix of:

• Fix an ...
• fix ...
• Fixed ...
• Resolves ...
• fixes ...

The case is inconsistent, etc.

They convey a lot of informational (which is nice), but it's not as presentable. I'm fine straying a bit more Kubernetes-like in our release notes, but not all the way.

[ianlancetaylor]

Simply requiring the change to include a change to the release notes doesn't work if the change is being sent by an occasional contributor who is not familiar with Go project conventions. We don't want to hold up that person's contribution by making them write release notes, and it's awkward for us to modify their CL to write release notes ourselves. And the reviewer may not have time to write a release note--again, we shouldn't hold up the contribution for the release notes.

So while I think we can encourage people to write release notes as we go, as you suggest, I don't think we can require it for every change that deserves release notes.

[andybons]

I'm fine with this, as long as everybody realizes it's not a 100% solution. Writing nice release notes does require some human attention to arrange things in a nice order, write some prose that connects sections nicely, and to make things consistent.

Totally agreed. I don't want to take out the human care that we put into this. I just want to make sure we focus our efforts on polishing rather than constructing.

[bradfitz]

Yeah, I think it's reasonable for us to try to do it for ourselves, but not for others.

We could even modify doc/go1.N.html in the same CL as the change. If we kept it sorted and diff-friendly with blank lines between additions, it might even survive reverts and such.

[rsc]

I think it's important to have something that's continuous throughout the cycle. That's clearly needed.

It's also important that the notes can be updated after the CL is merged. Some times we don't realize the CL is worth mentioning until later.

The tool already reads doc/go1.X.html and preserves modifications, so that if say the doc already has an entry for CL 12345 then the tool won't add a new one for RELNOTES=yes. (Right now the tool prints HTML but we'd probably want to modify it to update go1.X.html in place, at least optionally.)

Maybe a first step would be to run the tool nightly and send updates out to be committed. That would at least keep the release notes front-of-mind.

[rsc]

One way to avoid CLs falling through the cracks would be to require RELNOTES=yes/no in CL comments on every CL, and have the tool show the other CLs as "don't know yet". Might be too much work or too prone to false negatives.

In general more thought is needed on all this.

[bcmills]

One idea that @rsc suggested in a discussion earlier today: we could have GopherBot automatically create release-blocker issues for CLs with RELNOTES=yes, and CC them to the CL author and reviewers. Then whoever is triaging those issues could assign the release-note issue to someone from that set to do sooner rather than later, while the information about the CL is still fresh in their mind.

That would at least make the “unwritten release note” technical debt visible to our issue analysis and trackable as part of our regular issue-based planning. I hope it would also provide more an incentive for me (and others) to write the release notes in the CL instead of after the fact.

(CC @golang/osp-team)

[dmitshur]

This is implemented as of the Go 1.23 cycle by @jba, see issue #64169 and a golang-dev thread.