run.bash: document GO_TEST_SHORT and GO_TEST_TIMEOUT_SCALE; decide what to do with GOTESTONLY

[perillo]

What version of Go are you using (go version)?

$ go version
go version go1.16.4 linux/amd64

Does this issue reproduce with the latest release?

Yes.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE="on"
GOARCH="amd64"
GOBIN="/home/manlio/.local/bin"
GOCACHE="/home/manlio/.cache/go-build"
GOENV="/home/manlio/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE="*.local"
GOMODCACHE="/home/manlio/.local/lib/go/pkg/mod"
GONOPROXY=""
GONOSUMDB="*.local"
GOOS="linux"
GOPATH="/home/manlio/.local/lib/go:/home/manlio/src/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/lib/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/lib/go/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="go1.16.4"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build2218126867=/tmp/go-build -gno-record-gcc-switches"
GOROOT/bin/go version: go version go1.16.4 linux/amd64
GOROOT/bin/go tool compile -V: compile version go1.16.4
uname -sr: Linux 5.11.16-arch1-1
/usr/lib/libc.so.6: GNU C Library (GNU libc) release release version 2.33.
gdb --version: GNU gdb (GDB) 10.1

What did you do?

The run.bash script documents the GO_TEST_SHARDS and GO_BUILDER_NAME environment variables, but not the GOTESTONLY, GO_TEST_SHORT and GO_TEST_TIMEOUT_SCALE enviroment variables.

[heschi]

cc @rsc as a wild guess for an owner.

[bcmills]

CC @golang/release, since the primary use-case for most of these variables is to configure the Go dashboard builders.

[dmitshur]

Also CC @golang/release.

GO_TEST_SHORT is currently an internal implementation detail of the build system and not intended for users (see here). Before documenting it publicly, we'd need to decide that it should be made available to users (and supported as such). Issue #39054 may be relevant here.

I'm less familiar with GOTESTONLY but it looks like something made for builders (see CL 2523), given users can just specify a value by directly setting the -run flag. Although I suppose they can't if running cmd/dist indirectly via all.bash or so. I'm not sure if it should be made public, but if so, perhaps it should be renamed to be more consistent with the others (add underscore separators?).

GO_TEST_TIMEOUT_SCALE seems more generally useful, and perhaps worth documenting publicly.

Moving to NeedsDecision to decide whether to document these and consider them supported publicly, or document that they're an internal detail of the Go build system and not supported.

[perillo]

FYI:

• GO_TEST_TIMEOUT_SCALE is documented in https://dave.cheney.net/2015/09
• GO_TEST_SHORT and GO_TEST_TIMEOUT_SCALE where mentioned in
  https://groups.google.com/g/golang-dev/c/0pTKxEKhHSc/m/nFfRp21OBQAJ
• GO_TEST_SHORT was introduced in https://groups.google.com/g/golang-codereviews/c/2d3luNOd-Kk/m/ghzFBvuJ9-MJ

[gopherbot]

Change https://golang.org/cl/328771 mentions this issue: cmd/internal/moddeps: use a temporary directory for GOMODCACHE if needed

[dmitshur]

By now I think it's okay to document GO_TEST_SHORT and GO_TEST_TIMEOUT_SCALE variables and their effect, even if they're meant to be used internally in the project and its build system. The documentation can convey that fact.

We should probably remove or rename GOTESTONLY, it's not actively used by the build system as far as I can tell, and its naming pattern is inconsistent. That should wait until we're not in the freeze.

[gopherbot]

Change https://go.dev/cl/455519 mentions this issue: cmd/dist: remove GOTESTONLY environment variable

[gopherbot]

Change https://go.dev/cl/455517 mentions this issue: run.bash, cmd/dist: document GO_TEST_SHORT and GO_TEST_TIMEOUT_SCALE