From: Russ Cox Date: Mon, 5 Jun 2023 16:39:40 +0000 (-0400) Subject: doc/go1.21: document forward and backward compatibility X-Git-Tag: go1.21rc1~98 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=5db1e99bbd84ef7530e11eabad8d3c2a62366e5c;p=gostls13.git doc/go1.21: document forward and backward compatibility Also handle go test -c TODO. For #15513. For #56986. For #57001. Change-Id: I571ae25d8d8fcd44cb38ac16cdd2a1180016eb94 Reviewed-on: https://go-review.googlesource.com/c/go/+/500956 TryBot-Result: Gopher Robot Run-TryBot: Russ Cox Reviewed-by: David Chase --- diff --git a/doc/go1.21.html b/doc/go1.21.html index 575f93b9b5..c6af33ac6d 100644 --- a/doc/go1.21.html +++ b/doc/go1.21.html @@ -23,6 +23,26 @@ Do not send CLs removing the interior tags from such phrases.

+

+ The latest Go release, version 1.21, arrives six months after Go 1.20. + Most of its changes are in the implementation of the toolchain, runtime, and libraries. + As always, the release maintains the Go 1 promise of compatibility; + in fact, Go 1.21 improves upon that promise. + We expect almost all Go programs to continue to compile and run as before. +

+ +

+ Go 1.21 introduces a small change to the numbering of releases. + In the past, we used Go 1.N to refer to both the overall Go language version and release family + as well as the first release in that family. + Starting in Go 1.21, the first release is now Go 1.N.0. + Today we are releasing both the Go 1.21 language and its initial implementation, the Go 1.21.0 release. + These notes refer to “Go 1.21”; tools like go version will report “go1.21.0” + (until you upgrade to Go 1.21.1). + See “Go versions” in the “Go Toolchains” documentation for details + about the new version numbering. +

+

Changes to the language

@@ -123,13 +143,9 @@ Do not send CLs removing the interior tags from such phrases. Together, all these changes make type inference more powerful and inference failures less surprising.

-

- TODO: https://go.dev/issue/56986: extended backwards compatibility for Go -

-

- +

@@ -138,10 +154,55 @@ Do not send CLs removing the interior tags from such phrases.

Tools

+

+ Go 1.21 adds improved support for backwards compatibility and forwards compatibility + in the Go toolchain. +

+ +

+ To improve backwards compatibility, Go 1.21 formalizes + Go's use of the GODEBUG environment variable to control + the default behavior for changes that are non-breaking according to the + compatibility policy + but nonetheless may cause existing programs to break. + (For example, programs that depend on buggy behavior may break + when a bug is fixed, but bug fixes are not considered breaking changes.) + When Go must make this kind of behavior change, + it now chooses between the old and new behavior based on the + go line in the workspace's go.work file + or else the main module's go.mod file. + Upgrading to a new Go toolchain but leaving the go line + set to its original (older) Go version preserves the behavior of the older + toolchain. + With this compatibility support, the latest Go toolchain should always + be the best, most secure, implementation of an older version of Go. + See “Go, Backwards Compatibility, and GODEBUG” for details. +

+ +

+ To improve forwards compatibility, Go 1.21 now reads the go line + in a go.work or go.mod file as a strict + minimum requirement: go 1.21.0 means + that the workspace or module cannot be used with Go 1.20 or with Go 1.21rc1. + This allows projects that depend on fixes made in later versions of Go + to ensure that they are not used with earlier versions. + It also gives better error reporting for projects that make use of new Go features: + when the problem is that a newer Go version is needed, + that problem is reported clearly, instead of attempting to build the code + and instead printing errors about unresolved imports or syntax errors. +

-

- + To make these new stricter version requirements easier to manage, + the go command can now invoke not just the toolchain + bundled in its own release but also other Go toolchain versions found in the PATH + or downloaded on demand. + If a go.mod or go.work go line + declares a minimum requirement on a newer version of Go, the go + command will find and run that version automatically. + The new toolchain directive sets a suggested minimum toolchain to use, + which may be newer than the strict go minimum. + See “Go Toolchains” for details.

Go command

@@ -155,15 +216,28 @@ Do not send CLs removing the interior tags from such phrases. program.

+

+ The -C dir flag must now be the first + flag on the command-line when used. +

+

The new go test option -fullpath prints full path names in test log messages, rather than just base names.

- -

- +

+ The go test -c flag now + supports writing test binaries for multiple packages, each to + pkg.test where pkg is the package name. + It is an error if more than one test package being compiled has a given package name.] +

+ +

+ The go test -o flag now + accepts a directory argument, in which case test binaries are written to that + directory instead of the current directory.

Cgo