Skip to content

Commit

Permalink
doc/go1.21: document forward and backward compatibility
Browse files Browse the repository at this point in the history 
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 <[email protected]>
Run-TryBot: Russ Cox <[email protected]>
Reviewed-by: David Chase <[email protected]>
  • Loading branch information
@rsc
rsc committed Jun 5, 2023
1 parent 1b9c721 commit 5db1e99
Showing 1 changed file with 84 additions and 10 deletions.
94 changes: 84 additions & 10 deletions doc/go1.21.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,26 @@ <h2 id="introduction">DRAFT RELEASE NOTES — Introduction to Go 1.21</h2>
</strong>
</p>

<p>
The latest Go release, version 1.21, arrives six months after <a href="/doc/go1.20">Go 1.20</a>.
Most of its changes are in the implementation of the toolchain, runtime, and libraries.
As always, the release maintains the Go 1 <a href="/doc/go1compat">promise of compatibility</a>;
in fact, Go 1.21 <a href="#godebug">improves upon that promise</a>.
We expect almost all Go programs to continue to compile and run as before.
</p>

<p>
Go 1.21 introduces a small change to the numbering of releases.
In the past, we used Go 1.<i>N</i> 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.<i>N</i>.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 <code>go</code> <code>version</code> will report “<code>go1.21.0</code>”
(until you upgrade to Go 1.21.1).
See “<a href="/doc/toolchain#versions">Go versions</a>” in the “Go Toolchains” documentation for details
about the new version numbering.
</p>

<h2 id="language">Changes to the language</h2>

<p>
Expand Down Expand Up @@ -123,13 +143,9 @@ <h2 id="language">Changes to the language</h2>
Together, all these changes make type inference more powerful and inference failures less surprising.
</p>

<p><!-- https://go.dev/issue/56986 -->
TODO: <a href="https://go.dev/issue/56986">https://go.dev/issue/56986</a>: extended backwards compatibility for Go
</p>

<!-- https://go.dev/issue/57969 -->
<p>
<!-- add GOEXPERIMENT=loopvar -->
<!-- TODO(rsc): add GOEXPERIMENT=loopvar -->
</p>


Expand All @@ -138,10 +154,55 @@ <h2 id="language">Changes to the language</h2>
</p>

<h2 id="tools">Tools</h2>
<p>
Go 1.21 adds improved support for backwards compatibility and forwards compatibility
in the Go toolchain.
</p>

<p><!-- https://go.dev/issue/56986 -->
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
<a href="/doc/go1compat">compatibility policy</a>
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
<code>go</code> line in the workspace's <code>go.work</code> file
or else the main module's <code>go.mod</code> file.
Upgrading to a new Go toolchain but leaving the <code>go</code> 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 “<a href="/doc/godebug">Go, Backwards Compatibility, and GODEBUG</a>” for details.
</p>

<p><!-- https://go.dev/issue/57001 -->
To improve forwards compatibility, Go 1.21 now reads the <code>go</code> line
in a <code>go.work</code> or <code>go.mod</code> file as a strict
minimum requirement: <code>go</code> <code>1.21.0</code> 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.
</p>

<!-- https://go.dev/issue/15513 -->
<p>
<!-- support compiling all tests without running -->
To make these new stricter version requirements easier to manage,
the <code>go</code> 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 <code>go.mod</code> or <code>go.work</code> <code>go</code> line
declares a minimum requirement on a newer version of Go, the <code>go</code>
command will find and run that version automatically.
The new <code>toolchain</code> directive sets a suggested minimum toolchain to use,
which may be newer than the strict <code>go</code> minimum.
See “<a href="/doc/toolchain">Go Toolchains</a>” for details.
</p>

<h3 id="go-command">Go command</h3>
Expand All @@ -155,15 +216,28 @@ <h3 id="go-command">Go command</h3>
program.
</p>

<p>
The <code>-C</code> <code>dir</code> flag must now be the first
flag on the command-line when used.
</p>

<p><!-- https://go.dev/issue/37708, CL 463837 -->
The new <code>go</code> <code>test</code> option
<code>-fullpath</code> prints full path names in test log messages,
rather than just base names.
</p>

<!-- CL 466397 -->
<p>
<!-- cmd/go: make go test build multiple executables; The go test command now supports using the -c flag with multiple packages. -->
<p><!-- https://go.dev/issue/15513, CL 466397 -->
The <code>go</code> <code>test</code> <code>-c</code> flag now
supports writing test binaries for multiple packages, each to
<code>pkg.test</code> where <code>pkg</code> is the package name.
It is an error if more than one test package being compiled has a given package name.]
</p>

<p><!-- https://go.dev/issue/15513, CL 466397 -->
The <code>go</code> <code>test</code> <code>-o</code> flag now
accepts a directory argument, in which case test binaries are written to that
directory instead of the current directory.
</p>

<h3 id="cgo">Cgo</h3>
Expand Down

0 comments on commit 5db1e99

Please sign in to comment.