From 960cd141248b3e61ab651038097523a02dfa427b Mon Sep 17 00:00:00 2001 From: Dmitri Shuralyov Date: Fri, 24 May 2024 11:18:15 -0400 Subject: [PATCH] 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 Auto-Submit: Dmitri Shuralyov TryBot-Bypass: Dmitri Shuralyov Reviewed-by: Jonathan Amsterdam --- doc/README.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/doc/README.md b/doc/README.md index 3d0fb86102..bfd3c1e6a1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -41,9 +41,18 @@ 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 @@ -54,12 +63,13 @@ 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, 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. -- 2.48.1