goversioning

Taking a repository to v2

I'm using Go 1.11 modules for multiple repositories at this point. Right now I'm dealing with one that was already at a 1.x version. In combination with moving to go modules, I made some other breaking changes, so it's clear it's time to increment the major version of the repository. This means going to version 2.

Per "go command" documentation:

To preserve import compatibility, the go command requires that modules with major version v2 or later use a module path with that major version as the final element. For example, version v2.0.0 of example.com/m must instead use module path example.com/m/v2, and packages in that module would use that path as their import path prefix, as in example.com/m/v2/sub/pkg. Including the major version number in the module path and import paths in this way is called "semantic import versioning".

Source

Is this as simple as updating the first line of my go.mod file, appending /v2 to the module name? Or should I be creating a v2/ directory in my repository and moving all files into there?

Solution

  • There are two options for how to move to version 2: branches and subdirectories. You can read more about them (with better illustrations) at https://research.swtch.com/vgo-module.

    These two options are what make it possible for one version to depend on another. For example, when you implement version 2, you can update version 1 to depend on version 2 (but keep the same v1 API). Then, you only need to have one implementation of the logic for your library. This may or may not work well for you depending on the type of project, the support you want to provide, and the fixes it requires.

    Branches

    main: A -> B (v1.0.0) -> D (v1.0.1)
                         \
v2:                       -> C (v2.0.0)

    In this scenario:

    1. You start your project on the main branch,
    2. Make some commits (A and B),
    3. Tag v1.0.0.
    4. You decide to make a breaking change. So, you create a new branch (git checkout -b v2) and make your breaking changes. Your go.mod must now be updated so the module name ends with /v2 (it's essentially a new module!).
    5. You decide to fix a bug in v1, so you go back to that branch, make a new commit, and tag a new v1 version.

    When a user requires a particular version of your module, go will look in the two branches for which one provides the right module.

    Subdirectories

    What if you don't want to develop on branches? You can create a subdirectory for each major version. Version 1 stays at the top level, then new versions move into subdirectories:

    go.mod (module example.com/foo)
foo.go
v2/
  go.mod (module example.com/foo/v2)
  foo.go

    When you tag this repo with new versions, v1 will use the top level version. v2 tags will use the v2 subdirectory.