How are versions of a sub module managed?

Question

If a Go repository has a go.mod file in its root but also in a sub folder, how are versions of the submodule released?

By way of example, My team have been working with vault on our internal cli tool. We have ended up using:

github.com/hashicorp/vault/api <-- has a go.mod

and

github.com/hashicorp/vault/commands <-- doesn't have a go.mod so inherits from github.com/hashicorp/vault

I am trying to update vault/api to the latest version 1.3.3:

github.com/hashicorp/vault v1.3.3
github.com/hashicorp/vault/api v1.3.3

The problem is I get:

go: github.com/hashicorp/vault/api@v1.3.3: reading github.com/hashicorp/vault/api/api/go.mod at revision api/v1.3.3: unknown revision api/v1.3.3

Which I think is caused by this root module and a conflict.

Answer 1

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.

Defined here: https://github.com/golang/go/wiki/Modules#publishing-a-release

Answer 2

As an addition to answers above you can use go list command to see which versions of the module are available at the moment:

go list -m -versions github.com/hashicorp/vault/api
github.com/hashicorp/vault/api v1.0.1 v1.0.2 v1.0.3 v1.0.4 v1.1.0

Or use -u flag to see which (most recent) version you can upgrade to (if any):

go list -m -u github.com/hashicorp/vault/api
github.com/hashicorp/vault/api v1.0.3 [v1.1.0]

Where v1.0.3 is your current version, and [v1.1.0] is a most recent possible version.

go list docs

Answer 3

A Go Module is nothing but a collection of Go packages (Folders). Source files belonging to a package should be placed in separate folders of their own. It is a convention in Go to name this folder with the same name as the package.

Whenever you run the go get comment under any subfolders, it will update to current directory & any parent directory has a go.mod.

Answer 4

The versions of sub-modules aren't necessarily going lock-step with versions of parent modules. They should be treated as completely separate modules that just happen to live in the same repository / directory structure.

Check https://github.com/hashicorp/vault/releases for the official releases/tags -- Go supports hierarchical Git tags to mark versions of submodules. For example, while as of today the latest version of vault itself is 1.3.3, I only find vault/api at v1.0.4 (this is the latest tag with api/v1.0.4)

Just do a go get to get its latest version. You don't actually have to specify versions in go.mod when importing initially - the go tool will find the latest versions for you.