Merge branch 'master' into feature/internal-msan

Change-Id: I4a88d49272569a8fb9d1e9779ff390ba01f20e87

Author: mauri870

api/README

@@ -21,3 +21,6 @@ warning output from the go api tool. Each file should be named
 nnnnn.txt, after the issue number for the accepted proposal.
 (The #nnnnn suffix must also appear at the end of each line in the file;
 that will be preserved when next/*.txt is concatenated into go1.XX.txt.)
+
+When you add a file to the api/next directory, you must add at least one file
+under doc/next. See doc/README.md for details.

api/next/42888.txt

@@ -0,0 +1 @@
+pkg runtime/debug, func SetCrashOutput(*os.File) error #42888

api/next/61696.txt

@@ -0,0 +1 @@
+pkg sync, method (*Map) Clear() #61696

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