mirror of
https://github.com/golang/go
synced 2024-11-25 13:27:57 -07:00
960cd14124
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>
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# Release Notes
|
|
|
|
The `initial` and `next` subdirectories of this directory are for release notes.
|
|
|
|
## For developers
|
|
|
|
Release notes should be added to `next` by editing existing files or creating
|
|
new files. **Do not add RELNOTE=yes comments in CLs.** Instead, add a file to
|
|
the CL (or ask the author to do so).
|
|
|
|
At the end of the development cycle, the files will be merged by being
|
|
concatenated in sorted order by pathname. Files in the directory matching the
|
|
glob "*stdlib/*minor" are treated specially. They should be in subdirectories
|
|
corresponding to standard library package paths, and headings for those package
|
|
paths will be generated automatically.
|
|
|
|
Files in this repo's `api/next` directory must have corresponding files in
|
|
`doc/next/*stdlib/*minor`.
|
|
The files should be in the subdirectory for the package with the new
|
|
API, and should be named after the issue number of the API proposal.
|
|
For example, if the directory `6-stdlib/99-minor` is present,
|
|
then an `api/next` file with the line
|
|
|
|
pkg net/http, function F #12345
|
|
|
|
should have a corresponding file named `doc/next/6-stdlib/99-minor/net/http/12345.md`.
|
|
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
|
|
[Request] # short form, for symbols in the package being documented
|
|
[net/http] # package link
|
|
[#12345](/issue/12345) # GitHub issues
|
|
[CL 6789](/cl/6789) # Gerrit changelists
|
|
|
|
To preview `next` content in merged form using a local instance of the website, run:
|
|
|
|
```
|
|
go run golang.org/x/website/cmd/golangorg@latest -content='' -goroot=..
|
|
```
|
|
|
|
Then open http://localhost:6060/doc/next. Refresh the page to see your latest edits.
|
|
|
|
## For the release team
|
|
|
|
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.
|
|
Atomically (as close to it as possible) add that file to `_content/doc` directory
|
|
of the website repository and remove the `doc/next` directory in this repository.
|
|
|
|
To begin the next release development cycle, populate the contents of `next`
|
|
with those of `initial`. From the repo root:
|
|
|
|
> cd doc
|
|
> cp -r initial/* next
|
|
|
|
Then edit `next/1-intro.md` to refer to the next version.
|