doc/next: initial contents

Initialize the doc/next directory for the next release by copying the
contents of doc/initial into it.

Also, rewrite doc/README.md to add release instructions and to separate
information for developers from information for the release team.

Change-Id: Ie1e5c2ddae7a8d301e9b2f8a68925519648aa84d
Reviewed-on: https://go-review.googlesource.com/c/go/+/557535
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>

diff --git a/doc/README.md b/doc/README.md
index 827af1d3b193ff80b5f0c67fde91c5fa7f912948..9f70ea952eda0534f7143f93913e6e91f1836c9f 100644 (file)
--- a/doc/README.md
+++ b/doc/README.md
@@ -2,25 +2,37 @@
 
 The `initial` and `next` subdirectories of this directory are for release notes.
 
-At the start of a release development cycle, the contents of `next` should be deleted
-and replaced with those of `initial`.
-Release notes should be added to `next` by editing existing files or creating new files.
+## For developers
 
-To prepare the release notes for a release, run `golang.org/x/build/cmd/relnote generate`.
-That will merge the `.md` files in `next` into a single file.
+Release notes should be added to `next` by editing existing files or creating new files.
 
-The files are 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.
+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 `*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, for an api/next
-file with the line
+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
 
     pkg net/http, function F #12345
 
-there should be a file named net/http/12345.md.
+should have a corresponding file named `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.
+
+## For the release team
+
+At the start of a release development cycle, the contents of `next` should be deleted
+and replaced 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.
+
+To prepare the release notes for a release, run `golang.org/x/build/cmd/relnote generate`.
+That will merge the `.md` files in `next` into a single file.

diff --git a/doc/next/1-intro.md b/doc/next/1-intro.md
new file mode 100644 (file)
index 0000000..639550f
--- /dev/null
+++ b/doc/next/1-intro.md
@@ -0,0 +1,12 @@
+<!--
+NOTE: In this document and others in this directory, the convention is to
+set fixed-width phrases with non-fixed-width spaces, as in
+`hello` `world`.
+-->
+
+<style>
+  main ul li { margin: 0.5em 0; }
+</style>
+
+## Introduction to Go 1.23 {#introduction}
+

diff --git a/doc/next/2-language.md b/doc/next/2-language.md
new file mode 100644 (file)
index 0000000..61030bd
--- /dev/null
+++ b/doc/next/2-language.md
@@ -0,0 +1,3 @@
+## Changes to the language {#language}
+
+

diff --git a/doc/next/3-tools.md b/doc/next/3-tools.md
new file mode 100644 (file)
index 0000000..5638f24
--- /dev/null
+++ b/doc/next/3-tools.md
@@ -0,0 +1,6 @@
+## Tools {#tools}
+
+### Go command {#go-command}
+
+### Cgo {#cgo}
+

diff --git a/doc/next/4-runtime.md b/doc/next/4-runtime.md
new file mode 100644 (file)
index 0000000..1f8e445
--- /dev/null
+++ b/doc/next/4-runtime.md
@@ -0,0 +1 @@
+## Runtime {#runtime}

diff --git a/doc/next/5-toolchain.md b/doc/next/5-toolchain.md
new file mode 100644 (file)
index 0000000..0f4a816
--- /dev/null
+++ b/doc/next/5-toolchain.md
@@ -0,0 +1,7 @@
+## Compiler {#compiler}
+
+## Assembler {#assembler}
+
+## Linker {#linker}
+
+

diff --git a/doc/next/6-stdlib/0-heading.md b/doc/next/6-stdlib/0-heading.md
new file mode 100644 (file)
index 0000000..a992170
--- /dev/null
+++ b/doc/next/6-stdlib/0-heading.md
@@ -0,0 +1,2 @@
+## Standard library {#library}
+

diff --git a/doc/next/6-stdlib/99-minor/0-heading.md b/doc/next/6-stdlib/99-minor/0-heading.md
new file mode 100644 (file)
index 0000000..a98105e
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/0-heading.md
@@ -0,0 +1,3 @@
+### Minor changes to the library {#minor_library_changes}
+
+

diff --git a/doc/next/6-stdlib/99-minor/README b/doc/next/6-stdlib/99-minor/README
new file mode 100644 (file)
index 0000000..fac778d
--- /dev/null
+++ b/doc/next/6-stdlib/99-minor/README
@@ -0,0 +1 @@
+API changes and other small changes to the standard library go here.

diff --git a/doc/next/7-ports.md b/doc/next/7-ports.md
new file mode 100644 (file)
index 0000000..8bea3f8
--- /dev/null
+++ b/doc/next/7-ports.md
@@ -0,0 +1,2 @@
+## Ports {#ports}
+