Consider a non-standard toolchain with a Go version like "go1.21.1 X:loopvar" or "go1.21.1-issue63357", and a toolchain directive with the value "go1.21.1" exactly. When I first ran into this, it wasn't immediately clear to me if it would be better for that to cause the released Go toolchain "go1.21.1" to be downloaded and used, or for the non-standard toolchain to be deemed equal. Both options have some upsides. But whichever it is, it should be possible to figure out from the docs.

Consider that https://go.dev/doc/toolchain#version and https://go.dev/doc/toolchain#name include:

Any two Go versions can be compared to decide whether one is less than, greater than, or equal to the other.

Toolchains are compared by comparing the version V embedded in the name (dropping the initial go and discarding off any suffix beginning with -). For example, go1.21.0 and go1.21.0-custom compare equal for ordering purposes.

And https://go.dev/doc/toolchain#select includes:

If the go.work or go.mod file has a toolchain <tname> line and <tname> is newer than the default Go toolchain, then the go command runs <tname> instead.

So the documentation suggests the answer is they should be considered equal, at least for "go1.21.1-issue63357", and from briefly asking @rsc about this he expected that a non-standard toolchain built with a non-default GOEXPERIMENT isn't different enough to trigger toolchain downloads either.

What did you do?

$ cd $(mktemp -d)
$ git clone https://go.googlesource.com/go && cd go
$ git checkout go1.21.1

# edit first line of VERSION file to say "go1.21.1-issue63357"
# (presumably there may be code changes along with the suffix, but they're not needed for repro)
$ cd src && ./make.bash
$ ../bin/go version
go version go1.21.1-issue63357 darwin/arm64

$ cd src
$ GOEXPERIMENT=loopvar ./make.bash
$ ../bin/go version
go version go1.21.1 X:loopvar darwin/arm64

To reproduce this issue, I built a non-standard toolchain "go1.21.1-issue63357" (that said, the same behavior can be reproduced with a non-standard toolchain like "go1.21.1 X:loopvar"):

$ GOTOOLCHAIN=local go version
go version go1.21.1-issue63357 darwin/arm64

$ cd $(mktemp -d)
$ go mod init example.com/m
go: creating new go.mod: module example.com/m

$ go get go@1.21.0
go: downgraded go 1.21.1 => 1.21.0
go: added toolchain go1.21.1

Which results in the go.mod file:

module example.com/m

go 1.21.0

toolchain go1.21.1

Then I ran go version to see what toolchain would be selected.

What did you expect to see?

Expected the local non-standard toolchain to be used, Go version "go1.21.1-issue63357", and no toolchain download to be triggered:

$ go version
go version go1.21.1-issue63357 darwin/arm64

What did you see instead?

It triggered a toolchain download of "go1.21.1" and selected that one instead:

$ go version
go: downloading go1.21.1 (darwin/arm64)
go version go1.21.1 darwin/arm64

CC @rsc, @bcmills, @matloob.