x/website/_content/ref: inconsistent wording about version directive in go.mod

[alexbozhenko]

https://go.dev/ref/mod#go-mod-file-go says:

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 release version, such as 1.9, 1.14, or 1.21rc1.

https://go.dev/doc/toolchain#version says:

Released versions of Go use the version syntax ‘1.N.P’, denoting the Pth release of Go 1.N. The initial release is 1.N.0, like in ‘1.21.0’. Later releases like 1.N.9 are often referred to as patch releases.

There is no such "go release version" called 1.21.
So, according to the wording above, this is not supposed to work, right?

$ go version
go version go1.21.0 linux/amd64

$ cat main.go
package main

import "fmt"
import "runtime"

func main() {
        fmt.Println("hello from ", runtime.Version())
}

$ cat go.mod
module testing

go 1.21

$ go run main.go
hello from  go1.21.0

However, it does, effectively allowing any release in 1.21 "language version".

# updated go to 1.21.1

$ go version
go version go1.21.1 linux/amd64

$ go run main.go
hello from  go1.21.1

So should this wording be updated?

The version must be a valid Go release version, such as 1.9, 1.14, or 1.21rc1.

[seankhliao]

it should be updated, though 1.21 is sort of valid as it refers to the dev version

[alexbozhenko]

@seankhliao
When I have go 1.21.0 installed, and go.mod specifies 1.21.1 on go run it will download 1.21.1, and run with that version.

When I have go 1.21.0 installed, and go.mod specifies 1.21, (which is pre-release dev version, according to the docs), go run will not download the dev version.
Instead, it will run with whatever go version I have, be it 1.20.0 or 1.20.1

Should specifying "language version" only, without the patch, like 1.21 be prohibited in go.mod?

[seankhliao]

there is no single dev version to download, and we need a version that allows us to write code during the development cycle

[gopherbot]

Change https://go.dev/cl/530680 mentions this issue: _content/ref/mod: fix wording error