doc/next: add release notes for telemetry and the godebug directive

For #65614

Change-Id: I6274bdaba970cfb085af500fdaf8ed078202bfdc
Reviewed-on: https://go-review.googlesource.com/c/go/+/591380
Reviewed-by: David Chase <drchase@google.com>
Reviewed-by: Russ Cox <rsc@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/doc/next/3-tools.md b/doc/next/3-tools.md
index e73e8a73a39bd90de2e485387a0f7da4106eae33..73f931c102d6b943c15b4995241d74118d08550e 100644 (file)
--- a/doc/next/3-tools.md
+++ b/doc/next/3-tools.md
@@ -1,5 +1,31 @@
 ## Tools {#tools}
 
+### Telemetry
+
+<!-- go.dev/issue/58894, go.dev/issue/67111 -->
+Starting in Go 1.23, the Go toolchain can collect usage and breakage
+statistics that help the Go team understand how the Go toolchain is
+used and how well it is working. We refer to these statistics as
+[Go telemetry](/doc/telemetry).
+
+Go telemetry is an _opt-in system_, controlled by the
+[`go` `telemetry` command](/cmd/go/#hdr-Manage_telemetry_data_and_settings).
+By default, the toolchain programs
+collect statistics in counter files that can be inspected locally
+but are otherwise unused (`go` `telemetry` `local`).
+
+To help us keep Go working well and understand Go usage,
+please consider opting in to Go telemetry by running
+`go` `telemetry` `on`.
+In that mode,
+anonymous counter reports are uploaded to
+[telemetry.go.dev](https://telemetry.go.dev) weekly,
+where they are aggregated into graphs and also made
+available for download by any Go contributors or users
+wanting to analyze the data.
+See “[Go Telemetry](/doc/telemetry)” for more details
+about the Go Telemetry system.
+
 ### Go command {#go-command}
 
 Setting the `GOROOT_FINAL` environment variable no longer has an effect
@@ -23,18 +49,9 @@ It exits with a non-zero code if updates are needed.
 The `go` `list` `-m` `-json` command now includes new `Sum` and `GoModSum` fields.
 This is similar to the existing behavior of the `go` `mod` `download` `-json` command.
 
-<!-- go.dev/issue/67111 ("cmd/go: add go telemetry subcommand") -->
-The new `go` `telemetry` command can be used to view and configure the telemetry collection
-mode. Without arguments, it displays the current mode. With `local`, `on`, or `off`, it sets
-the collection mode. `go` `env` now lists two values: the `GOTELEMETRY` value, which
-contains the telemetry collection mode, and the `GOTELEMETRYDIR` value setting which contains
-the directory telemetry data and configuration are written to.
-
-<!-- go.dev/issue/58894 ("all: add opt-in transparent telemetry to Go toolchain") -->
-<!-- TODO: document Go 1.23 behavior (from https://go.dev/cl/559199, https://go.dev/cl/559519, https://go.dev/cl/559795, https://go.dev/cl/562715, https://go.dev/cl/562735, https://go.dev/cl/564555, https://go.dev/cl/570679, https://go.dev/cl/570736, https://go.dev/cl/582695, https://go.dev/cl/584276, https://go.dev/cl/585235, https://go.dev/cl/586138) -->
-
 <!-- go.dev/issue/65573 ("cmd/go: separate default GODEBUGs from go language version") -->
-<!-- TODO: document Go 1.23 behavior (from https://go.dev/cl/584218, https://go.dev/cl/584300, https://go.dev/cl/584475, https://go.dev/cl/584476) -->
+The new `godebug` directive in `go.mod` and `go.work` declares a
+[GODEBUG setting](/doc/godebug) to apply for the work module or workspace in use.
 
 ### Vet {#vet}
 
@@ -44,7 +61,7 @@ The `go vet` subcommand now includes the
 analyzer, which flags references to symbols that are too new for the version
 of Go in effect in the referring file. (The effective version is determined
 by the `go` directive in the file's enclosing `go.mod` file, and
-by any [`//go:build` constraints](https://pkg.go.dev/cmd/go#hdr-Build_constraints)
+by any [`//go:build` constraints](/cmd/go#hdr-Build_constraints)
 in the file.)
 
 For example, it will report a diagnostic for a reference to the