proposal: start using semantic versions for Go releases

[dmitshur]

At this time, the Go distribution uses versions that look like this:

go1
go1.12
go1.12.5
go1.11beta1
go1.11rc2

Those version strings are used both in the output of go version command, and as tag names in the source code repository.

Semantically, each version encodes a major, minor, and patch component, as well as optional pre-release metadata. However, the exact version string differs from semantic versions as defined by Semantic Versioning 2.0.0 specification in the following ways:

Differences

1. If a trailing version component is zero, it's omitted rather than preserved.
2. The second version component is referred to as "major version" rather than "minor version", and the third version component is referred to as "minor version" rather than "patch version". (For example, see https://github.com/golang/go/wiki/MinorReleases which by semver standard should be talking about patch versions, not minor versions.)
3. Pre-release versions are denoted by appending a label immediately following a minor version, rather than by appending a hyphen and a series of dot separated identifiers immediately following the patch version.
   4. The prefix is "go" rather than "v".

Go's current version strings are nice-looking and familiar, and this scheme was created before the existence and proliferation of https://semver.org. However, there are some disadvantages compared to following semver:

1. When someone talks about a "minor release" of Go, it's sometimes hard to know if they mean "x.Y.z" minor, or "x.y.Z" minor.

   For people who are familiar with semver, it's difficult to refer versions such as 1.12.6 as "minor releases" because semver refers to the increased version component as "patch", and it's hard to know if the target audience will understand what you actually meant.

   Following semver conventions, being as widespread as it is today, makes it possible to refer to all 3 version components without ambiguity or confusion.

2. Omitting the trailing version component makes it difficult to have clear conversation about those versions of Go releases.

   For example, when someone says "I was able to reproduce the problem with go1.12", it's hard to tell if they mean it happens only the exact version go1.12[.0] only, or if they mean any patch version, including go1.12, go.1.12.1, go1.12.2, go1.12.3, etc.

   Similarly, it's hard to refer to the initial release version with a trailing zero version component. It can be temping to explicitly say "try it with go1.12.0" in order to be clear you mean that exact version and not any other.

3. Modules have adopted semver, and many people are familiar with semver. Right now, the Go project uses two different version string schemes. By adopting semver for Go release versions, we can reduce it from two schemes to just one scheme. It's simpler, more consistent and fewer things for users to learn and keep in their head.

Performing any change to the existing version scheme has transitional costs. However, I think the medium- and long-term benefits will outweigh the costs by a wide enough margin to consider this.

This proposal is to consider changing the Go release version format to match that of Go module versions, which is semver-compliant. Specifically, the trailing zero version components should always be included, the "go" prefix changed to "v", and beta/RC pre-release suffixes represented in a way that satisfies semver.

The proposed version strings can look like this:

go2.0.0
go2.12.0
go2.12.5
go2.11.0-beta.1
go2.11.0-rc.2

Update on 2023-03-01: withdrew the suggestion to change the "go" prefix to "v". See #32450 (comment) for my rationale.

[ianlancetaylor]

I don't see anything "Go 2" about this proposal. It's not a language or library change, and could presumably take effect immediately. Any reason to keep the Go2 label here?

[aofei]

I love this proposal. I happened to have a problem with the runtime.Version today. So the naming of the Go versions caught my attention too. A huge thanks to you @dmitshur. 😁

However, I think we also need to pay attention to the Go versions without tags. According to the comment of the runtime.Version:

Version returns the Go tree's version string. It is either the commit hash and date at the time of the build or, when possible, a release tag like "go1.3".

The "commit hash" will disrupt the new naming rules you proposed. So, I think we can use some credits of Go modules. We can rename the original "commit hash" to "v0.0.0-20060102150405-0123456789ab". Then we can do something like semver.Compare(runtime.Version(), "v1.13.0").

[dmitshur]

could presumably take effect immediately

Do you mean retroactively changing all previous releases to start using a new version scheme, or to start using it for new releases only?

I proposed this for Go 2 in the sense we can consider starting to do this as of Go v2.0.0 release. I didn't think it was possible to retroactively change previous releases, and mixing-and-matching different versioning schemes within v1.x.x releases didn't seem great either.

However, we can consider those options too. In that case, the Go 2 label isn't necessary.

Edit: As @aofei mentioned, there are additional considerations such as output from runtime.Version, build constraints, etc.

[ianlancetaylor]

As discussed at https://github.com/golang/proposal/blob/master/design/28221-go2-transitions.md, it is, I think, unlikely that there will ever be a Go v2.0.0 release. But if you want to wait for that in case it happens, that is OK with me, in which case we should put this proposal on hold for now.

[dmitshur]

I think keeping it targeted at Go 2 and putting on hold for now is okay.

I wanted to write up this initial proposal to have a proposal to reference and gather initial feedback. For now, it can continue to target a hypothetical v2.0.0 release. I can take the time to flesh out the details and see what would it take to implement this concretely in an earlier v1.x.x release, and then we can re-consider it for that.

[aofei]

Wait until v2.0.0 to adopt this proposal? lol 😂

I agree with @ianlancetaylor, there should be no "Go2". If this proposal is to be adopted, then it should take effect immediately. In fact, I think we should have done this long ago. I mean this proposal should be proposed along with the Go modules proposal. Unfortunately, it does not. Why is Go urging everyone to strictly follow the semver, but Go itself doesn't do it? This should not happen.

[ianlancetaylor]

See #27255.

[dmitshur]

Thanks for pointing out #27255 to me. I hadn't found it when I was doing a search to see if this was proposed in the past. It covers an important subset of this proposal, so I plan to read through it and take the information there into account.

[robpike]

It would be a service to the community at large to have Go's module system use the strict semver model (https://semver.org/), which is three numeric fields separated by periods, followed by optional prerelease and build tags. There should always be 3 numbers and the 'v' prefix is spurious.

The argument for rejection in #27255 was, in essence, it's only us so it doesn't matter. But Go is part of a larger world and there are tools that work across languages. Also, large systems often contain many languages and consistency across their handling eases development. It would be better to lead by following the proposed standard than to stick to the unique form it has now.

[adg]

We have a lovely consistent set of versions dating all the way back to Go 1. If we change the way Go version strings are written then anything that consumes such strings needs to consume both the old format and the new one. Or am I missing something?

[dmitshur]

@adg I didn't include a section talking about the costs of implementing this proposal; perhaps I should have. You're absolutely right, that is one of the disadvantages of changing the version format.

I can think of some ways of dealing with it:

1. At some point long long in the future, v1.x.x versions may become very old and less actively looked at by most users. This is similar to how today, versions before the initial go1 release are rarely looked at in practice. It's still important to keep them for historical reasons, but I doubt tags like release.r57.1 or weekly.2012-01-27 see much use, so it's more okay that they use a different format.

2. If we limit the scope of this proposal to tags, then perhaps we can retroactively apply semver tags to all previous go1.x.x releases. That would be backwards compatible because all old tags would stay around. However, new users and tools can choose to start using semver tags and would only need to parse/handle those to have support for all versions of Go from v1.0.0 until the most recent version.