doc/README: suggest a way to preview next content, tweak release steps
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>
diff --git a/doc/README.md b/doc/README.md
index 3d0fb86..bfd3c1e 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -41,9 +41,18 @@
[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
@@ -54,12 +63,13 @@
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, delete the contents of `next`
-and replace them with those of `initial`. From the repo root:
+To begin the next release development cycle, populate the contents of `next`
+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.
