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.

Sign up for GitHub

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

Jump to bottom

doc: improve release notes #64169

Closed
7 tasks done
jba opened this issue Nov 15, 2023 · 52 comments
Closed
7 tasks done

doc: improve release notes #64169

jba opened this issue Nov 15, 2023 · 52 comments
Assignees
@jba
Labels
Documentation early-in-cycle A change that should be done early in the 3 month dev cycle. NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.23

Comments

@jba
Copy link
Contributor

jba commented Nov 15, 2023 •
edited
Loading

This issue covers a set of improvements to the Go release notes:

  • Convert existing release notes from HTML to Markdown.
  • Change definition lists to level 4 headings.
  • Check that there is a valid release note fragment for each file in api/next.
  • Write a command that prints a report for incomplete release note fragments.
  • Have that command check that there is a release note for an issue if there is a commit that mentions the issue.
  • Write a command to merge release note fragments into a single file.
  • Handle standard library symbol references in release note fragments like the go/doc/comment package would.
@jba jba self-assigned this Nov 15, 2023
gopherbot pushed a commit to golang/website that referenced this issue Nov 15, 2023
@jba
_content/doc: remove html release notes
807d485 
Now that the notes are in Markdown, we don't need the html files.

For golang/go#64169.

Change-Id: I25f0b636ed4101c38966a2b7d97ec5e5e3cb827e
Reviewed-on: https://go-review.googlesource.com/c/website/+/541975
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
gopherbot pushed a commit to golang/website that referenced this issue Nov 15, 2023
@jba
_content/doc: change relnote definition lists to headings
94d899b 
Since 1.7, the "Minor changes to the library" second has used
a definition list to describe the changes to each package.

Use level 4 headings instead. This removes one feature
that is not CommonMark-compliant. It paves the way for
using a CommonMark-compliant Markdown parser and renderer
for both display and generation of release notes.

For golang/go#64169.

Change-Id: I2327499971a2db4eee06ef35e3e41cd0d2f953b3
Reviewed-on: https://go-review.googlesource.com/c/website/+/541976
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/541975 mentions this issue: _content/doc: remove html release notes

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/541976 mentions this issue: _content/doc: change relnote definition lists to headings

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/542495 mentions this issue: relnote: a package for working with release notes

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/542515 mentions this issue: doc/next: directory for release note fragments

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/542516 mentions this issue: cmd/relnote,doc/next: add release note check

@dmitshur dmitshur mentioned this issue Nov 15, 2023
Closed
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/542615 mentions this issue: Add paragraph to 1.8 relnotes.

gopherbot pushed a commit to golang/website that referenced this issue Nov 15, 2023
@jba
_content/doc/go1.8: re-add reserved GOOS=zos value mention
4c30940 
For golang/go#64169.

Change-Id: Iac58322c3bdd20a86e5492e5cdbb8e92182962a6
Reviewed-on: https://go-review.googlesource.com/c/website/+/542615
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Run-TryBot: Jonathan Amsterdam <jba@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
@seankhliao seankhliao changed the title improve release notes doc: improve release notes Nov 15, 2023
gopherbot pushed a commit to golang/build that referenced this issue Nov 17, 2023
@jba
relnote: a package for working with release notes
44d28ab 
This CL starts a package that will be used in at least two places
as part of the current improvements to the release notes process.

- This repo will use it to find incomplete note fragments and
  also to merge them into a final document.

- The main repo will use it in tests that validate the fragments.

It has few dependencies because it will be vendored into the main repo.
Aside from the standard library, it depends only on rsc.io/markdown,
which itself depends only on some packages in x/tools and x/text.

For golang/go#64169.

Change-Id: Ifa558834f491bc6a249cbb540574fdb9009e9f8d
Reviewed-on: https://go-review.googlesource.com/c/build/+/542495
Run-TryBot: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
@dmitshur dmitshur added this to the Go1.23 milestone Jan 15, 2024
@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. early-in-cycle A change that should be done early in the 3 month dev cycle. labels Jan 15, 2024
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556455 mentions this issue: dashboard: disable x/build testing with Go 1.20

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556359 mentions this issue: all: use Go 1.21 for building services

gopherbot pushed a commit to golang/build that referenced this issue Jan 17, 2024
@dmitshur @gopherbot
dashboard: disable x/build testing with Go 1.20
9a6ab88 
The x/build repo is permitted to be outside of the Go support policy
and has dropped support for Go 1.20 just now in CL 556355. We need to
backport that from LUCI to the old infrastructure while the migration
is underway and both dashboards are being supported.

Updating this in the old infra is a bit more involved, but this code
will be going away after the migration so I'm not trying to refactor.

For golang/go#64169.

Change-Id: Ic5079e38dd13b5bfb56d4d430efb5c3919918d47
Reviewed-on: https://go-review.googlesource.com/c/build/+/556455
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
gopherbot pushed a commit to golang/build that referenced this issue Jan 17, 2024
@dmitshur @gopherbot
all: use Go 1.21 for building services
2e1eb85 
Use a newer supported version.

For golang/go#64169.

Change-Id: Ice8fea55951bf1615a04aca24a870556c281877a
Reviewed-on: https://go-review.googlesource.com/c/build/+/556359
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Carlos Amedee <carlos@golang.org>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556163 mentions this issue: cmd/relnote: add generate subcommand

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556162 mentions this issue: relnote: add headings for stdlib packages

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556161 mentions this issue: relnote: merge link references

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556160 mentions this issue: relnote: remove empty sections when merging

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556159 mentions this issue: relnote: add Merge function

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556164 mentions this issue: relnote: simplify CheckFragment

gopherbot pushed a commit to golang/build that referenced this issue Jan 18, 2024
@jba
relnote: add Merge function
a383c72 
Add a function that merges a tree of markdown files into a single file.

For golang/go#64169.

Change-Id: Ie3200d6cbe0e65f9c878de92c2d812b0ffbccc83
Reviewed-on: https://go-review.googlesource.com/c/build/+/556159
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/556655 mentions this issue: relnote: move merge tests to subdirectory

gopherbot pushed a commit to golang/build that referenced this issue Jan 18, 2024
@jba
relnote: remove empty sections when merging
fdfdde0 
Remove sections that have no content from the merged document.

For golang/go#64169.

Change-Id: Ic78b1e2dc46d14dcf885cef8ce0e7dd4a257298a
Reviewed-on: https://go-review.googlesource.com/c/build/+/556160
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/577658 mentions this issue: cmd/relnote: remove initial blank line from output

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/577915 mentions this issue: doc/README.md: note simpler symbol links

gopherbot pushed a commit to golang/build that referenced this issue Apr 10, 2024
@jba
cmd/relnote: remove initial blank line from output
c22ebb5 
The website code requires that the front matter
of a file start on the first line; there cannot be an initial
blank line. So remove it.

For golang/go#64169.

Change-Id: If268d23e15e19a125bab6ecf44c7c12ae728801d
Reviewed-on: https://go-review.googlesource.com/c/build/+/577658
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
gopherbot pushed a commit to golang/website that referenced this issue Apr 10, 2024
@jba
_content/doc: convert go1.22.html to markdown
1e09c04 
Convert the last release notes file from html to markdown.

See https://go.dev/cl/539755 for context.

The diffs were done by eye, because the screen grab for the local
server included the cookie warning, making the screentest diffs useless.

Along the way, fixed a bug: the html inadvertently used backticks
for code in one place.

For golang/go#64169.

Change-Id: I028982ad92a607974158a18496a1c3ac0a14d64a
Reviewed-on: https://go-review.googlesource.com/c/website/+/577775
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
@jba jba closed this as completed Apr 10, 2024
gopherbot pushed a commit that referenced this issue Apr 10, 2024
@jba
doc/README.md: note simpler symbol links
5b5d6f8 
Document that links to symbols in the standard library can be
written as "[foo]", without the actual link.

For #64169.

Change-Id: I9d8a33e85df70037320a169d55a2bb4a8a981ebf
Reviewed-on: https://go-review.googlesource.com/c/go/+/577915
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
@dmitshur dmitshur mentioned this issue Apr 26, 2024
Closed
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584396 mentions this issue: cmd/relnote: look for CLs that refer to proposals

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584301 mentions this issue: cmd/relnote: remove dead code

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584302 mentions this issue: cmd/relnote: make Go root directory a flag

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584398 mentions this issue: cmd/relnote: avoid TODOs for issues in existing relnotes

gopherbot pushed a commit to golang/build that referenced this issue May 9, 2024
@jba
cmd/relnote: look for CLs that refer to proposals
f5330cc 
Add a TODO for every merged CL that mentions an accepted proposal.

Also, move some functions from relnote.go to todo.go, where they
are used.

For golang/go#64169.

Change-Id: I023dab2bb9627be35c1b4ab90fe5dd597b6fc9ca
Reviewed-on: https://go-review.googlesource.com/c/build/+/584396
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
gopherbot pushed a commit to golang/build that referenced this issue May 9, 2024
@jba
cmd/relnote: remove dead code
88041c7 
For golang/go#64169.

Change-Id: I838a45104af33a973f2a3742eda2045386e9b66d
Reviewed-on: https://go-review.googlesource.com/c/build/+/584301
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/build that referenced this issue May 9, 2024
@jba
cmd/relnote: make Go root directory a flag
dfad60d 
It is a better way to represent that it is optional.

For golang/go#64169.

Change-Id: I7de85aa6615cfc27fc4a82fc0fa5d5892cd9ebea
Reviewed-on: https://go-review.googlesource.com/c/build/+/584302
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/build that referenced this issue May 9, 2024
@jba
cmd/relnote: avoid TODOs for issues in existing relnotes
c639adb 
Don't write a TODO for an issue that is mentioned in the release
notes.

For golang/go#64169.

Change-Id: I9829957cb07c997a1d763fc00a996aeb2a53ba17
Reviewed-on: https://go-review.googlesource.com/c/build/+/584398
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584615 mentions this issue: doc/README.md: mention adding the proposal issue

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/584401 mentions this issue: cmd/relnote: find cutoff date automatically

gopherbot pushed a commit to golang/build that referenced this issue May 10, 2024
@jba
cmd/relnote: find cutoff date automatically
4b28576 
Look for the date of CL that opened the tree to find the
cutoff for TODOs.

Add a flag for the date in case that doesn't work.

For golang/go#64169.

Change-Id: I756e5622339f5e1963c39b8e0bbd7eeb3fc23d85
Reviewed-on: https://go-review.googlesource.com/c/build/+/584401
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Russ Cox <rsc@golang.org>
gopherbot pushed a commit that referenced this issue May 16, 2024
@jba
doc/README.md: mention adding the proposal issue
ee0bf1d 
Inform users that every accepted proposal should be mentioned
in the release notes to avoid generating a TODO.

Also, clarify instructions for the release team.

For #64169.

Change-Id: I03921739af31fc93f4b5808b2c7c98e28ad3da11
Reviewed-on: https://go-review.googlesource.com/c/go/+/584615
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/587415 mentions this issue: doc/initial, doc/next: add draft notice to introduction

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/587435 mentions this issue: all: update x/build dependency

@gopherbot
Copy link
Contributor

Change https://go.dev/cl/587436 mentions this issue: cmd/golangorg: add doc/next page to preview draft release notes

gopherbot pushed a commit that referenced this issue May 22, 2024
@dmitshur @gopherbot
doc/initial, doc/next: add draft notice to introduction
614f228 
Go release notes always start out as a draft with a clear notice.
That notice is removed when the final release (go1.N.0) is made.
For example, the last time was in CL 562255.

Add this to the Go 1.23 draft and to the future fragment template.

Also switch to the main pkg.go.dev instance and use a relative issue
link in 3-tools.md while here.

For #64169.
For #65614.

Change-Id: I16bc0fa8a3a43ee7a9edd7fa253999041f1892e2
Reviewed-on: https://go-review.googlesource.com/c/go/+/587415
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@golang.org>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
gopherbot pushed a commit to golang/website that referenced this issue May 22, 2024
@dmitshur @gopherbot
all: update x/build dependency
9e5eadf 
Pull in latest changes to x/build/relnote. Its functionality
will be used when rendering the tip.golang.org/doc/next page.

For golang/go#64169.

Change-Id: I534dfb2f9b19495488e6025e057a39fea1f0a8d4
Reviewed-on: https://go-review.googlesource.com/c/website/+/587435
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
gopherbot pushed a commit to golang/website that referenced this issue May 22, 2024
@dmitshur @gopherbot
cmd/golangorg: add doc/next page to preview draft release notes
89cd698 
The improved release note process is being used starting with Go 1.23.
That means instead of a single doc/go1.23.html draft file in the main
Go repository, doc/next contains a set of release note fragments.
Having small, orthogonal files avoids merge conflicts, and a release
note test requires that release notes are written and included in the
same CL that's adding new APIs. As a result, the set of completed
release notes even before we enter the release freeze is greater than
ever before.

While it's possible to view those fragments using tip.golang.org
(e.g., by visiting https://tip.golang.org/doc/next), reading them
that way isn't practical. The relnote generate tool exists to merge
fragments into a complete Markdown document, and this tool will be
used when eventually moving a complete draft of Go 1.23 release notes
to x/website.

To aid the remaining work of completing the release note draft, this
change adds a dynamic /doc/next page to preview what the relnote
generate tool will produce. Combined with existing functionality of
the -tip flag, it makes https://tip.golang.org/doc/next display a live
preview of the checked-in release notes draft.

It can also be used to preview release note draft locally. For example,
if $HOME/gotip is a Go checkout where one is editing doc/next content:

go run golang.org/x/website/cmd/golangorg@latest -goroot=$HOME/gotip

Will serve a live preview at http://localhost:6060/go.dev/doc/next.
It can be slightly more convenient to refresh a browser without having
to re-run 'relnote generate'.

For golang/go#64169.
For golang/go#65614.

Change-Id: Ie1d3650076421a95a691dd84a554a113dd1187b1
Reviewed-on: https://go-review.googlesource.com/c/website/+/587436
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/587922 mentions this issue: doc/README: suggest a way to preview next content, tweak release steps

gopherbot pushed a commit that referenced this issue May 24, 2024
@dmitshur @gopherbot
doc/README: suggest a way to preview next content, tweak release steps
960cd14 
Smaller edits are usually fine to do without previewing, since Markdown
can be intuitive. But for larger changes including re-ordering sections
and such, it can be helpful to quickly see the end result. Write down a
way to do that.

Update the release steps to capture that the doc/next content will move
to x/website before RC 1, when the complete release note draft is ready.

For #64169.

Change-Id: Ie554ed5294ce819fd0689e2249e6013826f0c71f
Reviewed-on: https://go-review.googlesource.com/c/go/+/587922
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
@dmitshur dmitshur mentioned this issue May 31, 2024
Closed
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/591317 mentions this issue: cmd/relnote: improve tracking of mentioned issues and CLs

gopherbot pushed a commit to golang/build that referenced this issue Jun 7, 2024
@dmitshur @gopherbot
cmd/relnote: improve tracking of mentioned issues and CLs
ab83534 
Make the output of 'relnote todo' more useful:

- consider the existence of a *-stdlib/*-minor/.../nnn.md file to
  be equivalent to an explicit mention of an issue nnn; this way
  there's no need to enforce that a file like 12345.md must also
  have a comment like <!-- go.dev/issue/12345 -->
- improve the TODO wording of legacy RELNOTE= Gerrit comments when
  the release note isn't specified (beyond just "y" or "yes")
- track CLs that are mentioned (e.g., "CL nnn") and consider such
  mentions to mark legacy RELNOTE= Gerrit comments as handled
- sort provenances to remove a remaining source of non-deterministic
  output

With these changes, relnote todo | wc -l goes from 52 lines down to 8,
removing many mentions of proposals that are mentioned in nnn.md files
without an explicit comment, and a few legacy RELNOTE= Gerrit comments
that were reviewed as well.

For golang/go#64169.

Change-Id: If285c431854d279dd7dba6c145ba696ec003b351
Reviewed-on: https://go-review.googlesource.com/c/build/+/591317
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@jba jba

Labels
Documentation early-in-cycle A change that should be done early in the 3 month dev cycle. NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.23
Development

No branches or pull requests
3 participants
@dmitshur @gopherbot @jba