proposal: cmd/go: `go get -u` shouldn't bump minor release in `v0` packages.

[egonelbre]

Proposal Details

I've seen people break their project with a go get -u in various forums. It does seem that the main culprits for leaving projects in a broken state are either due to v0 packages or unversioned packages.

Currently https://go.dev/blog/publishing-go-modules#v0-the-initial-unstable-version recommends making breaking changes on v0 via bumping the minor release; and non-breaking changes via bumping patch release. For v1 and above, the breaking changes are indicated via bumping major release.

go get -u bumps the minor&patch release, which is only safe to do on v1+ packages based on the recommendations.

My proposal is to make go get -u default behaviour for v0 packages only to bump patch release. That way go get -u would become less problematic.

If the old behaviour is still desirable, something like go get -u=minor can be used.

At the moment I'm unable to think of any significant downsides with this approach; other than go get -u not bumping minor releases on golang.org/x packages. And of course go get -u logic becoming more complex.

Related issues:

• Pinning certain versions cmd/go: add option to prevent 'go get -u' from updating certain dependencies #29968
• Mentions a similar issue cmd/go: go get -u should not upgrade to unstable version #51922

[thediveo]

might this break tools such as go-mod-upgrade and not least the vscode go that doesn't know about changes in the go get behavior? Also, from my own experience there are two sides to the v0 coin: as there never was any guidance from the go project on v0 minor handling, quite some deps I work with are bumping the minor on new features, not necessarily API breaks. This proposal would create more friction for users of these modules. The UX would get more complex by first breaking existing tools and then "fixing" it by adding more options, and thus complexity.

[egonelbre]

might this break tools such as go-mod-upgrade

Doing a quick skim of go-mod-upgrade code, it doesn't look like such a change would break it; but I didn't do a deep analysis. It does a go list -u -m all to figure out what can be updated and then uses go get -d for every module to do a specific upgrade.

Also, from my own experience there are two sides to the v0 coin: as there never was any guidance from the go project on v0 minor handling...

@thediveo https://go.dev/blog/publishing-go-modules#v0-the-initial-unstable-version seems to be explicit guidance on minor version handling. Although, it is a blog-post and not in https://go.dev/doc/modules/version-numbers#in-development or https://go.dev/ref/mod#versions

If you add to the public API, make a breaking change to a v0 module, or upgrade the minor or version of one of your dependencies, increment the MINOR version for your next release. For example, the next release after v0.1.0 would be v0.2.0.

If you fix a bug in an existing version, increment the PATCH version. For example, the next release after v0.1.0 would be v0.1.1.

This proposal would create more friction for users of these modules.

I do agree with that, which is why I mentioned things like golang.org/x.

[thediveo]

@thediveo https://go.dev/blog/publishing-go-modules#v0-the-initial-unstable-version seems to be explicit guidance on minor version handling. Although, it is a blog-post and not in https://go.dev/doc/modules/version-numbers#in-development or https://go.dev/ref/mod#versions

Correct, it does mention both new API features as well as breaking changes for bumping minor. So we actually have both cases with all the ramifications.

At least, this should be somehow synchronized with downstream; I would suspect the vscode go plugin, gopls(?), Gland(?), and maybe some of the CLI tools.

[egonelbre]

I was thinking and there are alternate approaches such as:

1. Don't automatically bump on unstable at all,
2. Introduce a way to distinguish breaking and non-breaking minor version difference in v0. package

I don't have a good design on neither of these, but jotting down some ideas, maybe somebody has better ones.

Of course, not bumping unstable packages would be problematic in many scenarios, so this seems infeasible.

Making it possible to differentiate between breaking and non-breaking, would be possible in a few ways.

• Use a build tag, e.g. v0.1.0+break to make it obvious that it breaks things.
• Extend semver, e.g. v0.<major>.<minor>.<patch> (alternatively, v0.<major>.<minor>-<patch> or v0.<major>.<minor>+<patch>.
• Introduce entirely custom version syntax for unstable packages, e.g. u<major>.<minor>.<patch>.

Of course, none of these are a pretty solution.

---

In the ideal world people would build a stable version from the start, but for any complicated API it can be difficult to get things right in a few years; especially if it's not your primary job.

[willfaught]

Would this affect go get pkg too?