Skip to content

x/tools: automate major version upgrades for modules #32014

Open
@thepudds

Description

@thepudds

This is a spin out of #31543 ("cmd/go: creating v2+ modules has lower success rate than it could").

Background

Semantic import versioning 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 the required /v2 in their own module statements, or modules that accidentally do not update all import statements and accidentally 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 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" 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    NeedsInvestigationSomeone must examine and confirm this is a valid issue and not a duplicate of an existing one.ToolsThis label describes issues relating to any tools in the x/tools repository.modules

    Type

    No type

    Projects

    No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions