CC @rsc

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.

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)