Should the `go` directive in `go.mod` a semver version (including patch), or not?

[StefMa]

Go version

go version go1.22.2 darwin/arm64

Output of go env in your module/workspace:

GO111MODULE=''
GOARCH='arm64'
GOBIN=''
GOCACHE='/Users/stefan/Library/Caches/go-build'
GOENV='/Users/stefan/Library/Application Support/go/env'
GOEXE=''
GOEXPERIMENT=''
GOFLAGS=''
GOHOSTARCH='arm64'
GOHOSTOS='darwin'
GOINSECURE=''
GOMODCACHE='/Users/stefan/go/pkg/mod'
GONOPROXY=''
GONOSUMDB=''
GOOS='darwin'
GOPATH='/Users/stefan/go'
GOPRIVATE=''
GOPROXY='https://proxy.golang.org,direct'
GOROOT='/opt/homebrew/Cellar/go/1.22.2/libexec'
GOSUMDB='sum.golang.org'
GOTMPDIR=''
GOTOOLCHAIN='auto'
GOTOOLDIR='/opt/homebrew/Cellar/go/1.22.2/libexec/pkg/tool/darwin_arm64'
GOVCS=''
GOVERSION='go1.22.2'
GCCGO='gccgo'
AR='ar'
CC='cc'
CXX='c++'
CGO_ENABLED='1'
GOMOD='/dev/null'
GOWORK=''
CGO_CFLAGS='-O2 -g'
CGO_CPPFLAGS=''
CGO_CXXFLAGS='-O2 -g'
CGO_FFLAGS='-O2 -g'
CGO_LDFLAGS='-O2 -g'
PKG_CONFIG='pkg-config'
GOGCCFLAGS='-fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -ffile-prefix-map=/var/folders/m3/xsbbvz1j6sgd2_50b2m88vj80000gn/T/go-build1885746714=/tmp/go-build -gno-record-gcc-switches -fno-common

What did you do?

Given a simple go.mod file:

module github.com/cli/cli/v2

go 1.23

No other files are available.

Then I run go build.

What did you see happen?

When I run go build I get the following error:

go: downloading go1.23 (darwin/arm64)
go: download go1.23 for darwin/arm64: toolchain not available

What did you expect to see?

I don't expect an error.
According to this docs:

A go directive indicates that a module was written assuming the semantics of a given version of Go. The version must be a valid Go version, such as 1.9, 1.14, or 1.21rc1.

Heading over to the Go version link I can find this:

The syntax ‘1.N’ is called a “language version”. It denotes the overall family of Go releases implementing that version of the Go language and standard library.

Because of that, I would expect that I can use a "language version" as go directive.
But it is not working.
So either go behaves wrong (by not accepting a "langauge version" as a go directive), or the docs are not correct and needs to be changed. It seems only a "release name" is supported.
Looking at https://go.dev/doc/devel/release, I guess I can use each and every version mentioned here.
Hence, I can't use 1.21 (and up) anymore, since this release simply doesn't exist anymore.

I'm unsure what is the correct behaviour. Please let me know whats correct and what needs to be adjusted/fixed/changed.
Thanks! 🙃

Furhter reading where this is comming from (and for cress referencing):
cli/cli#9489

[gabyhelp]

Related Issues and Documentation

• cmd/go: Go modules initialised by go1.21.1 cannot be built using go1.20.8 #63279 (closed)
• cmd/go: go1.22 toolchain not available #65631 (closed)
• go mod edit: changing go versions in modules to invalid versions updates go.mod and causes weird problems #66491 (closed)
• x/website/_content/ref: inconsistent wording about version directive in go.mod #62707 (closed)
• cmd/compile: Go 1.22 changes support for modules that declare `go 1.0` #65528 (closed)
• tools/fix: go fix . does not work with patch in go version #68604 (closed)
• cmd/go: go toolchain version switch doesn't work when only language version is set in go.mod #65580 (closed)
• cmd/fix: fails to run on modules whose go directive value is in "1.n.m" format introduced in Go 1.21.0 #62584 (closed)
• cmd/go: `-help` and `go version` are broken when go.mod contains non-standard version #60956
• go build ignores GoVersion in go.mod file #58420 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[dmitshur]

This seems related or the same as #62278, which was fixed and backported to Go 1.22.4 (backport issue #67236). Can you try that version and see if it's fixed?

[StefMa]

Nice, thanks for the link!
I haven't tested it yet, but what I read so far seems that this fixes the bug.

However I still ask myself what the go team recommend to use as a version. The one with a patch, or without? What is considered as best practices?

[seankhliao]

The release versions are expected and generated by go tooling.

[StefMa]

Just wanted to confirm that 1.22.6 fixed that problem and can work with a language version:

The release versions are expected and generated by go tooling.

Thank you! 🙂