cmd/go: decide and document official recommendation for typical 'go' version in go.mod for open source libraries

[thepudds]

This is somewhat related to the recent discussion in #77653, but I think this would be nice to do regardless of whatever the conclusion might be for #77653.

Background

For open source libraries that intend to be used by the general ecosystem, there has been somewhat of an understanding that it is best for them to support at least the two officially supported versions of Go -- that is, the two newest major release versions of 1.N and 1.N-1, such as Go 1.26 and Go 1.25 currently.

Some open source libraries choose to support more than that, and some open source libraries might choose to support less than that, but the norm is often at least the 2 most recent versions if the intent is for an open source library to be widely used.

This choice became much more important due to the nice forward compatibility enhancements in #57001 ("proposal: extended forwards compatibility for Go").

During that conversation, one thing I had suggested was:

One thing to think about might be something official or some semi-official statement from the Go project about expected norms for an open source project in terms of how quickly new Go semantics are adopted (that is, how quickly a project's go line is updated), especially for public modules consumed as libraries, tools that appear within go.mod files, and so on. That might help it not be too fast, as well as help reduce debate on various open source issue trackers about when to update.

I think Russ seemed to agree with that:

A statement about expected norms in docs sounds good.

Examples of on-going confusion

This is still a fairly common topic on open source projects (for example, as people open up drive-by PRs or debate what it should be in sometimes long and often confusing discussions on an issue).

One area of related confusion I still see is around the exact meaning of something like go 1.25 in a go.mod file (without a patch number), and whether that is preferable to something like go 1.25.0, vs. whether they should pick something like go 1.25.7 or similar just because that is the latest available patch release.

Some quick probably representative examples:

kubernetes/kubernetes#137027 -- opened two weeks ago, issue suggests k8s should use go 1.25 in its go.mod files instead of go 1.25.0; k8s maintainer says better to do go 1.25.0 but also I think part of the response might be slightly incorrect in saying "no actual difference".

nats-io/nats-server#6530 -- some confusing discussion, also observes setup-go action authors seem to be applying a different interpretation of what go 1.22 in a go.mod means (and interpreting it as the latest available patch release, which is not what cmd/go does).

DataDog/datadog-agent#29340 -- somewhat confusing discussion of meaning and what should be done.

cli/cli#9489 -- somewhat confusing discussion of meaning and what should be done.

Suggestion

I think it would be nice to make a crisp official recommendation for what an open source Go library should do for its go version directive in its go.mod if it intends to be widely used, and we can then place it in the official documentation (ideally in a ~couple of places that are easy to find).

Let's initially set aside for now the exact wording and where it should be documented given that can be worked out after there is some level of agreement on what the recommendation should be.

Spot checking x/net and x/crypto, the last three go versions in their go.mod files seem to be go 1.23.0, go 1.24.0, and go 1.25.0.

That's probably reasonable as a model to follow -- support at least the 1.N and 1.N-1 Go releases, and default to recording the version using a .0 patch, unless there is some reason not to do so (e.g., if the library relies on a specific fix in a specific Go patch release, or if some required dependency already requires a higher patch, and so on).

There is a little bit of nuance around making sure it is seen as a recommendation and that individual projects might choose a different approach, but that exact nuance also probably can be hammered out along with the exact wording.

Alternative recommendations

Some perhaps less desirable alternatives:

1. pick a fixed patch release that is not .0, like always doing something like go 1.25.1 or go 1.25.3 given some people are averse to .0 releases. However, this might be too arbitrary, and might send the wrong message about .0 releases.

2. have a ~dynamic recommendation to use the latest patch release version that exists whenever the next major release happens (so something like go 1.25.7 if that was the latest patch release available when go1.26.0 was released). This version could be documented in some location and updated every major release. However, this might be too complicated and might also send the wrong message about .0 releases.

Finally, maybe this is already crisply documented somewhere, in which case maybe we should popularize it a bit more and maybe document it in a ~couple more places. 😅

CC @matloob @dmitshur

[gabyhelp]

Related Issues

• cmd/go: change `go mod init` default go directive to 1.(N-n).0 #74748 (closed)
• cmd/go: go directive is insufficiently documented for module authors to be able to make a decision about its value #30791 (closed)
• proposal: patch-level for releases & go.mod #56723 (closed)
• cmd/go: definition of "go" directive in go.mod conflicts between //go:build proposal and other uses #46201 (closed)
• x/website/_content/ref: inconsistent wording about version directive in go.mod #62707 (closed)
• cmd/go: inconsistent behavior when 'go' directive is missing from 'go.mod' #44976 (closed)

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

[mwriter]

related to the recent discussion

It seems to me that there is also a relation with yesterday's issue #77797

[thepudds]

Also, go mod init is already not silent. Current sample output:

$ go mod init foo
go: creating new go.mod: module foo
go: to add module requirements and sums:
        go mod tidy

Another form of documentation we could add is that go mod init could also output a sample command to change the go version along with a hint of why it might be useful to do so.

In other words, if the go mod init behavior goes back to its older behavior (that is, if proposal #77653 proceeds), then perhaps go mod init could output a command to optionally run to downgrade the go version if someone is planning on open sourcing the module as a library (w/ exact wording TBD).

On the other hand, if the new Go 1.26 go mod init version behavior continues on, then maybe go mod init could instead output a command to optionally upgrade to the latest go version.

[hyangah]

Most of the linked issues were from the established modules and projects, so it is less likely they benefit directly from go mod init. I think we need to keep looking for better channels. go mod edit, go audit, apidiff, ...

[mwriter]

go audit

And what is meant by this? Language and security analyzers?

[hyangah]

go audit

And what is meant by this? Language and security analyzers?

That's an idea that has been floating around among some of us - packaging govulncheck, api checks, etc in the go command. I thought there was already an open issue or discussion, but I just realized there isn't yet.

[ldemailly]

While on the topic, how about dropping the .0 and having go line back to a language version, which doesn’t change across patches

[zsyo]

While on the topic, how about dropping the .0 and having go line back to a language version, which doesn’t change across patches

​I agree with the idea of treating a major release as a unified language version. To that end, I would prefer that go mod init defaults to 1.N.0 consistently across all patch releases of the same major version.

​This approach offers two key benefits:
​1. Prevents Forced Upgrades: It avoids the friction of forcing team members to upgrade their local toolchains just because someone initialized a project using a slightly newer patch (e.g., 1.26.2 vs 1.26.0), which usually contains no language changes.
2. Flexibility and Consistency: Retaining the trailing .0 maintains a consistent versioning format while allowing teams the flexibility to specify a higher patch version if a critical security fix or bug fix is required for the project.

​Essentially, using 1.N.0 as the baseline provides the best balance between ecosystem stability and the ability to opt into specific toolchain requirements when they actually matter.

[ldemailly]

if we agree .0 is the right patchlevel then why is it needed at all

[myaaaaaaaaa]

We have tools like goimports that automatically updates imports on save. How about a similar tool for the Go version? It could analyze the package code, and then automatically pick the lowest version that supports all the features used in the package.

[mwriter]

but I just realized there isn't yet

Yep, I also have a lot of ideas about this, but I don't dare to throw it all out publicly yet.

How about a similar tool for the Go version?

Yep, you're repeating an idea from a recent issue #77797.

[rittneje]

I think there are a few general guidelines that would be good to recommend.

First, if your module already supports 1.N, you should be mindful of when you drop support for it by changing go.mod to 1.(N+1), since it leaves users that are still on 1.N in the lurch, unable to upgrade. Exactly when to drop 1.N is going to vary based upon the user base, and how much effort the author wants to continue to invest in the presumably diminishing returns. Continuing to support 1.N while it is still supported by the Go team is probably a reasonable rule of thumb, but not the right choice in all cases.

It would also be good to mention the possibility of using //go:build directives to allow using newer standard library functions and features only when compiling under the newer toolchain. This allows older clients to remain compatible while still allowing newer clients to get the benefits of the newer toolchain.

Patch versions (or "minor revisions" as the Go toolchain calls them) I think fall into a similar boat. If you are intending to support 1.N, then you may want to support 1.N.0 specifically for maximum flexibility. However, if your module relies on some standard library fix, you should be honest about this in your go.mod. My general suspicion is that modules intended for a wide audience should tend to hover around patch version 0, whereas internal or personal modules will stick with the version of the toolchain being used.

(There is an unfortunate hole in semver here. For example, suppose you rely on a bug fix that went into 1.24.7 and 1.25.1. But if you put 1.24.7 into the go.mod file, it will allow 1.25.0 users to use your module. I don't think there is any way around this. Maybe go.mod needs a way to account for it.)

Meanwhile, you should avoid updating the patch version in the go directive just for the sake of it, as this leads to churn with little if any benefit to the ecosystem. You should generally only bother if you need the fix the patch provides. However, I'm not sure there is a good answer to "how long after a patch version is released is it reasonable for a module to declare it as a requirement because it needs the fix?"

Also, for whatever go directive is in go.mod, make sure you at least test with that specific toolchain version to prove compatibility. Do not just rely on a newer toolchain's imperfect ability to emulate the older one. And for the purposes of shift-left, you should consider developing the module with that version locally as well (possibly via a dev container), but this may not be practical in all cases.