cmd/go: document new architecture feature build tags

Also mention in release notes.

Change-Id: Ifddfc6d2fdaae07c0774ad917838b0fdf9c0b0fe
Reviewed-on: https://go-review.googlesource.com/c/go/+/452559
Reviewed-by: Bryan Mills <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Run-TryBot: Russ Cox <[email protected]>

doc/go1.20.html

@@ -85,7 +85,11 @@ <h3 id="go-command">Go command</h3>
 </p>
 
 <p><!-- https://go.dev/issue/45454 -->
-  TODO: <a href="https://go.dev/issue/45454">https://go.dev/issue/45454</a>: provide build tags for architecture environment variables
+  The <code>go</code> command now defines
+  architecture feature build tags, such as <code>amd64.v2</code>,
+  to allow selecting a package implementation file based on the presence
+  or absence of a particular architecture feature.
+  See <a href="/cmd/go#hdr-Build_constraints"><code>go</code> <code>help</code> <code>buildconstraint</code></a> for details.
 </p>
 
 <p><!-- https://go.dev/issue/50332 -->

src/cmd/go/internal/help/helpdoc.go

@@ -851,6 +851,8 @@ During a particular build, the following build tags are satisfied:
 	  GOOS environment variable.
 	- the target architecture, as spelled by runtime.GOARCH, set with the
 	  GOARCH environment variable.
+	- any architecture features, in the form GOARCH.feature
+	  (for example, "amd64.v2"), as detailed below.
 	- "unix", if GOOS is a Unix or Unix-like system.
 	- the compiler being used, either "gc" or "gccgo"
 	- "cgo", if the cgo command is supported (see CGO_ENABLED in
@@ -880,11 +882,45 @@ in addition to illumos tags and files.
 Using GOOS=ios matches build tags and files as for GOOS=darwin
 in addition to ios tags and files.
 
-To keep a file from being considered for the build:
+The defined architecture feature build tags are:
+
+	- For GOARCH=386, GO386=387 and GO386=sse2
+	  set the 386.387 and 386.sse2 build tags, respectively.
+	- For GOARCH=amd64, GOAMD64=v1, v2, and v3
+	  correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
+	- For GOARCH=arm, GOARM=5, 6, and 7
+	  correspond to the arm.5, arm.6, and arm.7 feature build tags.
+	- For GOARCH=mips or mipsle,
+	  GOMIPS=hardfloat and softfloat
+	  correspond to the mips.hardfloat and mips.softfloat
+	  (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
+	- For GOARCH=mips64 or mips64le,
+	  GOMIPS64=hardfloat and softfloat
+	  correspond to the mips64.hardfloat and mips64.softfloat
+	  (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
+	- For GOARCH=ppc64 or ppc64le,
+	  GOPPC64=power8, power9, and power10 correspond to the
+	  ppc64.power8, ppc64.power9, and ppc64.power10
+	  (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
+	  feature build tags.
+	- For GOARCH=wasm, GOWASM=satconv and signext
+	  correspond to the wasm.satconv and wasm.signext feature build tags.
+
+For GOARCH=amd64, arm, ppc64, and ppc64le, a particular feature level
+sets the feature build tags for all previous levels as well.
+For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
+This ensures that code making use of v2 features continues to compile
+when, say, GOAMD64=v4 is introduced.
+Code handling the absence of a particular feature level
+should use a negation:
+
+	//go:build !amd64.v2
+
+To keep a file from being considered for any build:
 
 	//go:build ignore
 
-(any other unsatisfied word will work as well, but "ignore" is conventional.)
+(Any other unsatisfied word will work as well, but "ignore" is conventional.)
 
 To build a file only when using cgo, and only on Linux and OS X: