1# Release Notes
2
3The `initial` and `next` subdirectories of this directory are for release notes.
4
5## For developers
6
7Release notes should be added to `next` by editing existing files or creating
8new files. **Do not add RELNOTE=yes comments in CLs.** Instead, add a file to
9the CL (or ask the author to do so).
10
11At the end of the development cycle, the files will be merged by being
12concatenated in sorted order by pathname. Files in the directory matching the
13glob "*stdlib/*minor" are treated specially. They should be in subdirectories
14corresponding to standard library package paths, and headings for those package
15paths will be generated automatically.
16
17Files in this repo's `api/next` directory must have corresponding files in
18`doc/next/*stdlib/*minor`.
19The files should be in the subdirectory for the package with the new
20API, and should be named after the issue number of the API proposal.
21For example, if the directory `6-stdlib/99-minor` is present,
22then an `api/next` file with the line
23
24    pkg net/http, function F #12345
25
26should have a corresponding file named `doc/next/6-stdlib/99-minor/net/http/12345.md`.
27At a minimum, that file should contain either a full sentence or a TODO,
28ideally referring to a person with the responsibility to complete the note.
29
30If your CL addresses an accepted proposal, mention the proposal issue number in
31your release note in the form `/issue/NUMBER`. A link to the issue in the text
32will have this form (see below). If you don't want to mention the issue in the
33text, add it as a comment:
34```
35<!-- go.dev/issue/12345 -->
36```
37If an accepted proposal is mentioned in a CL but not in the release notes, it will be
38flagged as a TODO by the automated tooling. That is true even for proposals that add API.
39
40Use the following forms in your markdown:
41
42	[http.Request]                     # symbol documentation; auto-linked as in Go doc strings
43	[Request]                          # short form, for symbols in the package being documented
44	[net/http]                         # package link
45	[#12345](/issue/12345)             # GitHub issues
46	[CL 6789](/cl/6789)                # Gerrit changelists
47
48To preview `next` content in merged form using a local instance of the website, run:
49
50```
51go run golang.org/x/website/cmd/golangorg@latest -goroot=..
52```
53
54Then open http://localhost:6060/doc/next. Refresh the page to see your latest edits.
55
56## For the release team
57
58The `relnote` tool, at `golang.org/x/build/cmd/relnote`, operates on the files
59in `doc/next`.
60
61As a release cycle nears completion, run `relnote todo` to get a list of
62unfinished release note work.
63
64To prepare the release notes for a release, run `relnote generate`.
65That will merge the `.md` files in `next` into a single file.
66Atomically (as close to it as possible) add that file to `_content/doc` directory
67of the website repository and remove the `doc/next` directory in this repository.
68
69To begin the next release development cycle, populate the contents of `next`
70with those of `initial`. From the repo root:
71
72    > cd doc
73    > cp -r initial/* next
74
75Then edit `next/1-intro.md` to refer to the next version.
76