doc/README.md: mention adding the proposal issue

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>

diff --git a/doc/README.md b/doc/README.md
index c2b320711f66008e796bda0cfb3c3686f6f21e73..f608f34fbdbf2ab0dd9bd47dc962fce9bed817e3 100644 (file)
--- a/doc/README.md
+++ b/doc/README.md
@@ -27,6 +27,16 @@ should have a corresponding file named `doc/next/6-stdlib/99-minor/net/http/1234
 At a minimum, that file should contain either a full sentence or a TODO,
 ideally referring to a person with the responsibility to complete the note.
 
+If your CL addresses an accepted proposal, mention the proposal issue number in
+your release note in the form `/issue/NUMBER`. A link to the issue in the text
+will have this form (see below). If you don't want to mention the issue in the
+text, add it as a comment:
+```
+<!-- go.dev/issue/12345 -->
+```
+If an accepted proposal is mentioned in a CL but not in the release notes, it will be
+flagged as a TODO by the automated tooling. That is true even for proposals that add API.
+
 Use the following forms in your markdown:
 
        [http.Request]                     # symbol documentation; auto-linked as in Go doc strings
@@ -35,14 +45,20 @@ Use the following forms in your markdown:
 
 ## For the release team
 
-At the start of a release development cycle, the contents of `next` should be deleted
-and replaced with those of `initial`. From the repo root:
+The `relnote` tool, at `golang.org/x/build/cmd/relnote`, operates on the files
+in `doc/next`.
+
+As a release cycle nears completion, run `relnote todo` to get a list of
+unfinished release note work.
+
+To prepare the release notes for a release, run `relnote generate`.
+That will merge the `.md` files in `next` into a single file.
+
+To begin the next release development cycle, delete the contents of `next`
+and replace them with those of `initial`. From the repo root:
 
     > cd doc
     > rm -r next/*
     > cp -r initial/* next
 
 Then edit `next/1-intro.md` to refer to the next version.
-
-To prepare the release notes for a release, run `golang.org/x/build/cmd/relnote generate`.
-That will merge the `.md` files in `next` into a single file.