Golang: separate versioning of multiple modules

Question

Imagine I have a repo github.com/user/golang-examples and I provision to version each example module within it separately:

guthub.com/user/golang-examples
  /modA
    /go.mod
    /pkgA1
    /pkgA2

  /modB
    /go.mod
    /pkgB1
    /pkgB2

(I know the idiom is “one repo - one module” but there are usecases for multimodule projects, too, so this is not the subject of the discussion)

At the same time, semantic git tagging (v1.0.0, v2.0.0 etc.) happens on the level of repo, not its subfolders. This makes it impossible to tag modules separately, for example

1. First, modA overtakes modB in development by major version, and tag v2.0.0 is pushed at the repo level, with intent to version modA
2. Later, when one wants to upgrade modB to v2, one can’t push the same v2.0.0 git tag for the second time to version modB.

How can this task be accomplished in line with golang’s versioning paradigm? Again, this is about multi-module project. Obvious solution to split modules into repos is kind of unfavourable here because the overarching “examples” semantics of the top repo is desired.

Thanks!

Waldon

Answer 1

Ok, after a continued search I found this resource: https://github.com/go-modules-by-example/index/blob/master/009_submodules/README.md

Applied to my situation, the answer is to use:

• for module modA use tags of the form modA/vX.Y.Z (using semantic versioning)
• for module modB use tags of the form modB/vX.Y.Z

For the context, the citation from the above lint:

The official modules proposal predicts that most projects will follow the simplest approach of using a single Go module per repository, which typically means creating one go.mod file located in the root directory of a repository.

For some reason, I still cannot find a correct docs/specs reference.

Waldon

Answer 2

This is the docs for tag submodules of golang:
https://github.com/golang/go/wiki/Modules#publishing-a-release

A new module version may be published by pushing a tag to the repository that contains the module source code. The tag is formed by concatenating two strings: a prefix and a version.

The version is the semantic import version for the release. It should be chosen by following the rules of semantic import versioning.

The prefix indicates where a module is defined within a repository. If the module is defined at the root of the repository, the prefix is empty, and the tag is just the version. However, in multi-module repositories, the prefix distinguishes versions for different modules. The prefix is the directory within the repository where the module is defined. If the repository follows the major subdirectory pattern described above, the prefix does not include the major version suffix.

For example, suppose we have a module example.com/repo/sub/v2, and we want to publish version v2.1.6. The repository root corresponds to example.com/repo, and the module is defined in sub/v2/go.mod within the repository. The prefix for this module is sub/. The full tag for this release should be sub/v2.1.6.

Bondstone