From b0799674677921ba87cd71f42ba6467478a66c63 Mon Sep 17 00:00:00 2001 From: Alan Donovan Date: Fri, 26 Jan 2024 11:19:22 -0500 Subject: [PATCH] doc/README: clarify instructions - State that new markdown files belong in doc/next. - Give hints on correct markdown syntax. For #64169 Change-Id: Ied70e7ac443530c910eea2992ca6e303bbc10499 Reviewed-on: https://go-review.googlesource.com/c/go/+/558855 Reviewed-by: Dmitri Shuralyov Reviewed-by: Dmitri Shuralyov LUCI-TryBot-Result: Go LUCI Reviewed-by: Jonathan Amsterdam --- doc/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/doc/README.md b/doc/README.md index 9f70ea952e..3bb8412ad5 100644 --- a/doc/README.md +++ b/doc/README.md @@ -13,16 +13,24 @@ 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 -`*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, an `api/next` file with the line +`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 `net/http/12345.md`. +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. +Use the following forms in your markdown: + + [`http.Request`](/pkg/net/http#Request) # symbol documentation + [#12345](/issue/12345) # GitHub issues + [CL 6789](/cl/6789) # Gerrit changelists + ## For the release team At the start of a release development cycle, the contents of `next` should be deleted