From 6037c8a87745f96307bb4ffab965aa39f4cf1806 Mon Sep 17 00:00:00 2001 From: Jonathan Amsterdam Date: Mon, 22 Jan 2024 13:20:07 -0500 Subject: [PATCH] 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 Reviewed-by: Dmitri Shuralyov Reviewed-by: Dmitri Shuralyov Reviewed-by: Jonathan Amsterdam --- doc/README.md | 40 ++++++++++++++++--------- doc/next/1-intro.md | 12 ++++++++ doc/next/2-language.md | 3 ++ doc/next/3-tools.md | 6 ++++ doc/next/4-runtime.md | 1 + doc/next/5-toolchain.md | 7 +++++ doc/next/6-stdlib/0-heading.md | 2 ++ doc/next/6-stdlib/99-minor/0-heading.md | 3 ++ doc/next/6-stdlib/99-minor/README | 1 + doc/next/7-ports.md | 2 ++ 10 files changed, 63 insertions(+), 14 deletions(-) create mode 100644 doc/next/1-intro.md create mode 100644 doc/next/2-language.md create mode 100644 doc/next/3-tools.md create mode 100644 doc/next/4-runtime.md create mode 100644 doc/next/5-toolchain.md create mode 100644 doc/next/6-stdlib/0-heading.md create mode 100644 doc/next/6-stdlib/99-minor/0-heading.md create mode 100644 doc/next/6-stdlib/99-minor/README create mode 100644 doc/next/7-ports.md diff --git a/doc/README.md b/doc/README.md index 827af1d3b1..9f70ea952e 100644 --- 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`. +## For developers + Release notes should be added to `next` by editing existing files or creating new files. -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. +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. -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. - -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 index 0000000000..639550f92a --- /dev/null +++ b/doc/next/1-intro.md @@ -0,0 +1,12 @@ + + + + +## Introduction to Go 1.23 {#introduction} + diff --git a/doc/next/2-language.md b/doc/next/2-language.md new file mode 100644 index 0000000000..61030bd676 --- /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 index 0000000000..5638f240a5 --- /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 index 0000000000..1f8e445e0b --- /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 index 0000000000..0f4a816479 --- /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 index 0000000000..a992170d43 --- /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 index 0000000000..a98105e8cc --- /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 index 0000000000..fac778de05 --- /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 index 0000000000..8bea3f8fbc --- /dev/null +++ b/doc/next/7-ports.md @@ -0,0 +1,2 @@ +## Ports {#ports} +