internal/testenv: update Builder docs with LUCI builder names

Also include some advice to avoid using this when possible. It makes
tests more prone to breaking under infrastructure changes.

Change-Id: Ifb2848742347eb0c937547dd888ab2cad3343f2d
Reviewed-on: https://go-review.googlesource.com/c/go/+/703115
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>

diff --git a/src/internal/testenv/testenv.go b/src/internal/testenv/testenv.go
index 0f6c9bbdad43de6dea5355c7e529636dedaaabeb..947340ce83ea127f1428cfb9305b03496d38eba6 100644 (file)
--- a/src/internal/testenv/testenv.go
+++ b/src/internal/testenv/testenv.go
@@ -34,8 +34,13 @@ import (
 // environment might cause environment checks to behave erratically.
 var origEnv = os.Environ()
 
-// Builder reports the name of the builder running this test
-// (for example, "linux-amd64" or "windows-386-gce").
+// Builder reports the name of the builder running this test. For example,
+// "gotip-linux-amd64_avx512-test_only" or "go1.24-windows-arm64" on LUCI,
+// or "linux-amd64" on our old infrastructure. Prefer using runtime.GOOS,
+// runtime.GOARCH, race.Enabled, reading the OS version, checking CPU
+// feature flags with internal/cpu, etc. over parsing builder names when
+// possible. When matching builder names, prefer a fuzzy match instead
+// of a strict comparison.
 // If the test is not running on the build infrastructure,
 // Builder returns the empty string.
 func Builder() string {