build: use a zero for third digit for major release, such as 'go1.21.0'

[thepudds]

Summary

#32450 and #27255 proposed adopting semantic versioning for Go releases. semver has a very specific definition, which means fully adopting it has significant challenges, including it raises certain expectations that don't apply, there are differences between what the go project vs. semver considered a "major release", and other sample problems mentioned here or here. Personally, I don't think it would be worthwhile to adopt semver for Go releases.

This is intentionally a narrower proposal, which is just to start adding the .0 to major releases at some point, such as go1.23.0.

Rationale 1: Stop old releases from using code they don't understand

Part of the context for this proposal is the auto-upgrading forward compatibility proposal (#57001), which would be a transition point for how Go versions overall are managed, and the related possible transition in the semantics of loop variables (#56010).

In #57001 (comment), Russ wrote (responding to @rittneje):

As an example, one of our teams tends to end up on officially unsupported versions because qualifying new releases is a large effort and doing it every six months is not feasible. It would be better if an explicit failure could be induced in older compilers (e.g., by adding a new directive to go.mod) instead of just assuming no one would use one.

For exactly the same kind of backwards compatibility, unrecognized lines in dependency go.mod files are ignored. So we've painted ourselves into a bit of a corner where the best we can do is prepare K versions that recognize that they don't understand the new code and then issue the K+1'th version supporting the new code. The only thing we really have control over is the choice of K. In the quoted text I was assuming K=1. Maybe we should do K=2, but I wouldn't want to do more than that and I'm not even sure K=2 is worth it.

Older go versions I think stretching back to go1.14 will reject a go.mod if the go line has a go version with a third digit, so always using three digits in the go.mod could be a way to cause even very old versions of cmd/go to fail if for example #56010 is adopted.

The majority of gophers would get the good behavior described in #57001 because most gophers would land within that K=1 or K=2 window, but this would be a broader enforcement mechanism that handles old Go releases outside that K window.

Example error (playground link):

go: errors parsing go.mod:
go.mod:3: invalid go version '1.25.0': must match format 1.23

In other words:

• "enforcement & good errors" for most gophers
• "enforcement & subotimal but google-able error" for much smaller subset of gophers using versions outside that K window

...which might be better than "unexpected semantics & no error" for that subset of gophers.

Rationale 2: Current source of confusion

I think releases like go1.20 have been a source of confusion, including when gophers are talking to each other about what version they are currently running or should run. Some older comments in a similar spirit:

@mvdan wrote in #29984:

I too have wished for 1.11 to be 1.11.0 for a while. Too many users think they're running the latest 1.11 because they're on 1.11. "What do you mean the latest 1.11? I am on 1.11"

@bcmills wrote in #29984:

Personally, I think it's pretty confusing to have the first patch version in the 1.11 line be named go1.11 rather than go1.11.0. [...] The lack of minor-version on the first release buries a major clue to the user that there might be more recent versions available. I would like to see us release Go 1.12 as go1.12.0 instead of go1.12.

Some costs

1. Code or scripts that parse go versions would need to be updated or at least visited to ensure they handle the new format.

   • (In some cases, code that knows how to parse go1.23.1 might already handle go1.23.0).
   • (Also, any such code or scripts that is looking at go.mod already would need to be updated to handle the three digits for patch releases in go.mod proposed in #57001).

2. Documentation, blogs, books, and so on would also need to be updated or be slightly stale.

   • (However, the impact of being stale or the work to update for a third digit might be small compared to the impact of #57001 overall).

In general, using a transition point to introduce even more change is a terrible idea in some cases. In other cases, it can be helpful to piggyback a desirable change on top of another transition. That said, I'm not sure which of those cases this proposal is. ;-)

Alternative

An alternative form of this proposal might be to just use zero in the third digit in go.mod and nowhere else, which might be a smaller change, but that then might be a ~mild source of confusion if it is inconsistent with other go version uses.

[mvdan]

I continue having to explain around the confusion of the missing trailing dot-zero. Especially when users report bugs on my projects written in Go, as they say "I'm on Go 1.X", and that is very ambiguous - especially given that many new users see go version go1.20 and assume that there are no 1.20.x releases to watch out for, like Bryan says.

In other words, some people understand 1.20 to mean 1.20.0 (the first bugfix version), whereas others understand it to mean 1.20.x (the latest bugfix version), and that isn't likely to change.

An alternative form of this proposal might be to just use zero in the third digit in go.mod and nowhere else

Perhaps unsurprisingly, I wouldn't support this alternative :) I want to make the release versions explicit.

[ianlancetaylor]

CC @golang/release

[rsc]

This may be an idea whose time has come. I'll reserve feedback for later to let more people weigh in. I just wanted to reply to this:

go: errors parsing go.mod:
go.mod:3: invalid go version '1.25.0': must match format 1.23

This error only happens for the work module's go.mod. In dependency go.mod files, the parser runs in 'lax' mode, where it is more forgiving of things it doesn't understand. For the go line, if the lax parser sees go 1.25.0 or even go 1.25asdfasdfasdf, it will treat it the same as go 1.25. I did this a few releases back specifically to make changes along these lines safer. Of course, that was back when I thought we'd want Go 1.19 to be able to build and run dependencies that said go 1.25.0. Now with #57001 we don't. A failure of vision I suppose.

[thepudds]

Hi @rsc 👋

This error only happens for the work module's go.mod. In dependency go.mod files, the parser runs in 'lax' mode, where it is more forgiving of things it doesn't understand.

Ah, I didn't check that.

That might close off this avenue for helping with broader enforcement for things like #56010.... though maybe there is some other potential modification... but that's perhaps unlikely, and probably even less likely to be as natural as just using three digits in the existing go line.

As an example of another possibility, this seems to fail even in lax parsing mode for a dependency:

go go1.25.0

... but that stutter is a bit ugly. (Playground link, in case anyone wants to try variations).

I suppose cmd/go could take on doing some transformation to a breaking format when something like go mod tidy or go get is run at a sufficiently high go version line... but maybe this is a well painted corner after all. 😅

prepare K versions that recognize that they don't understand the new code and then issue the K+1'th version supporting the new code. The only thing we really have control over is the choice of K. In the quoted text I was assuming K=1. Maybe we should do K=2, but I wouldn't want to do more than that and I'm not even sure K=2 is worth it.

As a side note, I'd vote for a K > 1. There's a decently long tail of people out there that don't quite move at the pace of the Go project's officially supported versions...

[thepudds]

And of course, when it comes to K, it could be worth cheating time a bit by adding some tiny bit of knowledge in a patch release, similar to how go1.11 was the first Go version of modules, but go1.9.7 and go1.10.3 picked up a tiny bit of knowledge to help with the transition.

Picking sample numbers, something like:

• go1.19.10 and go1.20.5 could learn that go 1.23 or higher in a go.mod is a hard error
• go1.21 could learn how to auto upgrade
• go1.23 could change loop variable semantics

Alternatively, instead of the first bullet there picking a specific version to consider a hard error, a patch release could roll back the three-digit lax parsing in dependencies, or something along those lines. Given this would be done now with foreknowledge, it could be a friendlier error.

Finally, it looks like the lax parser also rejects a go directive more more than two terms, which means something like go language 1.23.0 would be rejected, but that's probably not a perfect choice either. (It allows go v1.23.0 ;-).

[rsc]

I think we can leave intentionally breaking old toolchains to #57001. Writing 'go 1.21.0' would work today in the past many Go versions. So this issue can just be about "should we call the next release Go 1.21.0" instead of "Go 1.21"?

Probably we should call it "Go 1.21.0" so that when people say "Go 1.21" it is clear they mean the overall sequence of point releases and not specifically the first one. For example in Docker golang you can ask for go1.21.1 but as I understand it you can't ask for go1.20. Saying "FROM golang:1.20" gets you the latest 1.20 point release.

Is there anything that would break if we call the next major release Go 1.21.0? We know version strings can handle 'go1.21.0' because they handle 'go1.21.1'.

[dmitshur]

Is there anything that would break if we call the next major release Go 1.21.0? We know version strings can handle 'go1.21.0' because they handle 'go1.21.1'.

At least some code that parses Go versions and/or tags may have special cases to account for ".0" currently being left out, and that would need to change (for example, see here) to treat go1.21.0 the same as go1.21.

Code that constructs Go download URLs by relying on the current pattern (e.g. "https://go.dev/dl/" + version + suffix) instead of using the "filename" field from the go.dev/dl/?mode=json API response would also presumably need to be updated to handle .0 releases.

I don't see discussion of what, if anything, should happen to pre-release versions like RC 1 above. More changes may be needed to handle pre-release versions depending on the answer to that.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[thepudds]

Hi @dmitshur

I don't see discussion of what, if anything, should happen to pre-release versions like RC 1 above. More changes may be needed to handle pre-release versions depending on the answer to that.

Personally, I think the pre-release versions could be left alone and there could be go1.21rc1, go1.21.0, and go1.21.1, or at least, that was the intent of this intentionally narrow proposal. I think they are not a major source of confusion today. They don't follow semver, but I think that's OK for some of the reasons mentioned above, and of course there would be additional costs if they were to change as well. That said, others might have different opinions.