cmd/go/internal/help: add documentation for language version downgrading

This change adds documentation for language version downgrading using
build constraints.

Fixes #68161
For #61894

Change-Id: I283a51afd7020c9fd1f5469a6a93fd814ba32f7e
Reviewed-on: https://go-review.googlesource.com/c/go/+/595475
Reviewed-by: Robert Findley <rfindley@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 972f9e111f6db1e83e352bc289e5d084456361f5..e87e6ebe465587b6311f9a931bfc7cdae09518b9 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -1994,6 +1994,9 @@
 //
 //     //go:build
 //
+// Build constraints can also be used to downgrade the language version
+// used to compile a file.
+//
 // Constraints may appear in any kind of source file (not just Go), but
 // they must appear near the top of the file, preceded
 // only by blank lines and other comments. These rules mean that in Go
@@ -2116,6 +2119,10 @@
 // with a "// +build" prefix. The gofmt command will add an equivalent //go:build
 // constraint when encountering the older syntax.
 //
+// In modules with a Go version of 1.21 or later, if a file's build constraint
+// has a term for a Go major release, the language version used when compiling
+// the file will be the minimum version implied by the build constraint.
+//
 // # Build modes
 //
 // The 'go build' and 'go install' commands take a -buildmode argument which

diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go
index 791013dbfeaa381c4a81071ddcd44373a4a32b87..29c0a56321a602dca7ce44bf077a26aadc15724c 100644 (file)
--- a/src/cmd/go/internal/help/helpdoc.go
+++ b/src/cmd/go/internal/help/helpdoc.go
@@ -835,6 +835,9 @@ line comment that begins
 
        //go:build
 
+Build constraints can also be used to downgrade the language version
+used to compile a file.
+
 Constraints may appear in any kind of source file (not just Go), but
 they must appear near the top of the file, preceded
 only by blank lines and other comments. These rules mean that in Go
@@ -954,5 +957,9 @@ only when building the package for 32-bit x86.
 Go versions 1.16 and earlier used a different syntax for build constraints,
 with a "// +build" prefix. The gofmt command will add an equivalent //go:build
 constraint when encountering the older syntax.
+
+In modules with a Go version of 1.21 or later, if a file's build constraint
+has a term for a Go major release, the language version used when compiling
+the file will be the minimum version implied by the build constraint.
 `,
 }