Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
andybons opened this issue Jul 17, 2018 · 7 comments

Comments

@andybons
Copy link
Member

commented Jul 17, 2018

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

@andybons andybons added this to the Go1.12 milestone Jul 17, 2018

@andybons andybons self-assigned this Jul 17, 2018

@bradfitz

This comment has been minimized.

Copy link
Member

commented Jul 17, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Jul 17, 2018

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

This comment has been minimized.

Copy link
Member Author

commented Jul 17, 2018

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

This comment has been minimized.

Copy link
Member

commented Jul 17, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Aug 13, 2018

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

This comment has been minimized.

Copy link
Contributor

commented Aug 13, 2018

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.

@rsc rsc added NeedsFix and removed NeedsDecision labels Sep 26, 2018

@bradfitz bradfitz removed the early-in-cycle label Nov 3, 2018

@bradfitz bradfitz modified the milestones: Go1.12, Unplanned Nov 3, 2018

@bcmills

This comment has been minimized.

Copy link
Member

commented Jun 14, 2019

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)

@andybons andybons removed their assignment Sep 18, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.