doc: mention language downgrading via //go:build

[dominikh]

Reading https://go.dev/doc/toolchain, only upgrading the language version on a per-file basis is shown, not downgrading.

It does say that

The language version can be changed on a per-file basis by using a build constraint

but that's a bit implicit, considering this is a major change from how module versions and build constraints used to interact.

https://pkg.go.dev/cmd/go#hdr-Build_constraints doesn't mention the semantics of version build constraints, either.

[mknyszek]

CC @rsc

[oliverpool]

I got bitten by this in #64308 where implementing a polyfill for a previous version of the compiler would not work:

//go:build !go1.21

package main

// min is a pseudo-polyfill for go1.21 min function
func min(a, b int) int {
	if a < b {
		return a
	}
	return b
}

Currently the doc states:

For example, a module containing code that uses the Go 1.21 language version should have a go.mod file with a go line such as go 1.21 or go 1.21.3. If a specific source file should be compiled only when using a newer Go toolchain, adding //go:build go1.22 to that source file both ensures that only Go 1.22 and newer toolchains will compile the file and also changes the language version in that file to Go 1.22.

It would be helpful to add something like:

For a module to use builtin functions introduced in a later version of Go, use a proxy function with two files implementing it. One with the //go:build go1.22 build constraint which directly calls the builtin, the other with //go:build !go1.22, with a polyfill of the (not-yet available) builtin.

[oliverpool]

the language version declared by the go directive of the go.mod is not used to satisfy build constraints (which are checked against the currently running Go toolchain).

Edit: I just realized that this is only relevant for builtins (since stdlib or syntax changes require 2 mutually excluding Go files)

[gopherbot]

Change https://go.dev/cl/595475 mentions this issue: cmd/go/internal/help: add documentation for language version downgrading

[gopherbot]

Change https://go.dev/cl/602936 mentions this issue: _content/doc: be more specific about build constraint downgrades