Repository: go
Issue: x/tools: automate major version upgrades for modules
Labels: NeedsInvestigation,modules,Tools

This is a spin out of #31543 ("cmd/go: creating v2+ modules has lower success rate than it could").

### Background

[Semantic import versioning](https://research.swtch.com/vgo-import) places the major version in module paths and import paths for v2+ modules, such as:
 * `module github.com/some/mod/v2` in the author's `go.mod`.
 * `require github.com/some/mod/v2 v2.0.0` in the consumer's `go.mod`.
 * `import "github.com/some/mod/v2/some/pkg"` in the consumer's `.go` files, and in the author's `.go` files when the module's packages import other packages within the same v2+ module.

This approach has value, but empirically it currently seems it can be a challenge to do correctly the first time (e.g., modules with v2 major version semver tags that are [missing](https://github.com/prometheus/prometheus/blob/v2.9.1/go.mod) the required `/v2` in their own `module` statements, or modules that accidentally do not update all import statements and [accidentally](https://github.com/santhosh-tekuri/jsonschema/blob/3187f5dd695e7a7fe4c2254be6fb4f0737fec928/httploader/httploader.go#L20) depend on the v1 version of themselves, etc.)

It also creates additional work for authors and consumers if a module's major version increments, such as from v1 to v2, or v3 to v4, etc.

### Suggestion

Tooling should be able to help here in a substantial way.

[github.com/marwan-at-work/mod](https://github.com/marwan-at-work/mod) is great for people who know about it and who are willing to trust it.

However, a tool from the broader community won't have the penetration and impact of something from golang.org, or at least it would likely take much longer to get a similar type of penetration following a typical trajectory for a community tool.

Therefore, the suggestion here is to create a golang.org/x utility that can edit `go.mod` and `.go` files to simplify the workflow for authors and consumers of v2+ modules. It might be possible to port `marwan-at-work/mod` itself, especially with the creation in #31761 of the x/mod repo that exposes APIs for module mechanics (such as an API for `go.mod` parsing).

Three sample use cases:

1. If someone is adopting modules for the first time as the author of a v2+ set of packages, ideally the utility would:
   * set the `/vN` in the module path in the `module` statement in the `go.mod` 
   * update any import paths in the module's `.go` files if needed
2. If the author is later changing the major version for a v2+ module, ideally the utility would:
   * set the `/vN` in the module path in the `module` statement in the `go.mod` 
   * update any import paths in the module's `.go` files if needed
3. If a consumer wants to use a particular major version of a v2+ module, ideally the utility would:
   * set the `require` statement properly in the consumer's `go.mod` 
   * update any import paths in the consumer's `.go` files if needed

I think `marwan-at-work/mod` can currently do all of those things.

Perhaps one day similar functionality could live in cmd/go (e.g., the closed #27248), but it seems more practical to start with something in golang.org/x.

### Non-goals

The suggestion here is that this golang.org/x utility would **not** do anything with VCS tagging, nor do anything for creating `/vN` subdirectories for anyone following the ["Major Subdirectory"](https://research.swtch.com/vgo-module) approach.  Also, it would probably be reasonable for a first version to error out if used by a consumer that has a `replace` for the module of interest (or, that could be handled more gracefully).

CC @bcmills @jayconrod @marwan-at-work