cmd/go: introduce subcommand to upgrade/downgrade import paths according to semantic import versioning

[marwan-at-work]

Summary

If you have a repository with a number of sub packages that import each other and you'd like to introduce a breaking change (tagging a new major version), then you have to manually update all import paths everywhere in that repository including the go.mod file.

I propose we introduce two new subcommands go mod upgrade and go mod downgrade that will do the above automatically.

It would also be nice to include a flag to jump a few versions so that repositories already tagged with say v8.0.0 can run go mod upgrade -t=v8

I've written a tool that does this as a reference: https://github.com/marwan-at-work/mod

And I've used it to open a few PRs for popular packages such as google/martian#262

What version of Go are you using (go version)?

1.11

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

Darwin

What did you do?

Wanted to update a Go repository to a new major version

What did you expect to see?

An automated tool that updates the go.mod file as well as all import paths.

What did you see instead?

Had to do it manually.

[bcmills]

cmd/go itself doesn't normally rewrite source code (that's more a job for cmd/fix).
In this particular case, the functionality seems analogous to golang.org/x/tools/refactor/rename.

It also doesn't seem specific to major versions: for example, one might want to perform conceptually the same operation to start a fork of a module with a new module path. That doesn't fit nicely into the upgrade/downgrade dichotomy.

I'm happy to see external tools to do this (perhaps in x/tools?), but I don't think it's a good fit for cmd/go itself.

[marwan-at-work]

@bcmills makes sense. Maybe go help modules can refer to whatever tool to help you upgrade major versions (or change import paths in general as you said) -- this way users know where to go when they want to do such thing.

Lastly, my only semantic comment is that upgrading to a new version in my opinion is not a "fix". It's part of the regular flow of development. So I'd expect go mod to be able to do that since it's a module functionality and more so a rule. That said, it's not a biggie as long as there's a canonical way that people can easily find out about when they need to upgrade/downgrade modules.

[bcmills]

it's not a biggie as long as there's a canonical way that people can easily find out about when they need to upgrade/downgrade modules.

Nobody outside of your module should “need” to update their import paths when you publish a new major version: that's the whole point of semantic import paths. (If the different major versions need to share some sort of global state to avoid conflicts, you can do that by defining the old version to forward to the new, or by using a third internal module to store the shared state.)

So the only person who “needs” to upgrade import paths is you (the creator of the new module path), and you know about it already!

For everyone else, updating to the new major version should be more of a “cleanup” than a “fix”, strictly speaking: it shouldn't change the behavior of the code, but does express the underlying structure more directly.

[marwan-at-work]

@bcmills hah! True. But I was actually referring to package owners as opposed to packages users. Package owners should have an easy way to find out how to go about upgrading their own packages w/ go modules when they get to that point. For now, the Go Wiki maybe is enough? If so, happy to close this issue. Thanks!

[bcmills]

Let's start with the wiki. (Honestly, I think the wiki may be more discoverable than go help text anyway...)
If it's in the wiki and folks still ask about it frequently, then we can consider other options.

Thanks again for all the great tooling contributions, mod included!

[thepudds]

@bcmills

cmd/go itself doesn't normally rewrite source code (that's more a job for cmd/fix).
...
I'm happy to see external tools to do this (perhaps in x/tools?), but I don't think it's a good fit for cmd/go itself.

Would it make sense to re-open this for tracking purposes, perhaps re-labeled such that it is not specifically about cmd/go?

In other words, it makes sense why this was closed initially, but maybe makes sense to re-purpose it a bit and keep as a tracking issue for a possible future cmd/fix or golang.org/x tool?

@marwan-at-work, not to put you too much on the spot, but do you think your current implementation would lend itself to living in something like golang.org/x, or would it need a bunch of changes?

CC @jayconrod

[thepudds]

Slightly more context:

While semantic import versioning has value, there is also some transition pain that flows from semantic import versioning, and the best answer to me seems to be better tooling to reduce that pain in a material way.

https://github.com/marwan-at-work/mod is great for people who know about it and who are willing to trust it.

However, I hope that type of functionality will eventually be in go fix or at least some golang.org/x tool, including because a tool from the broader community won't have the penetration and impact of something in the go tools themselves, or at least would likely take much longer to get a similar type of penetration under a typical trajectory for a community tool.