Understanding Go Module Paths, Versioning, and Pseudo‑Versions

This article, part of the Tencent Cloud "Cloud Recommendation Experts" column, explains how Go defines module paths and what changes Go Modules bring.

Module Path : Defined in the go.mod file, the module path uniquely identifies a Go module and serves as the prefix for all package paths within that module. A directory containing a go.mod file is the module’s root.

Package Path : A package path combines the module path with a sub‑directory relative to the module root. For example, the package golang.org/x/net/html resides under the module golang.org/x/net.

Key takeaways: a single repository may contain multiple modules, and a module may contain multiple packages.

The module path should convey at least two pieces of information: the purpose of the module and where to obtain it.

Version Numbers and Compatibility : Go follows semantic versioning vMAJOR.MINOR.PATCH. Increment the major version for incompatible changes, the minor version for backward‑compatible feature additions, and the patch version for bug fixes. Pre‑release versions (e.g., v1.2.3‑pre) and build metadata (e.g., +meta) are also supported. Versions with a major version of 0 or a pre‑release suffix are considered unstable and are not subject to compatibility guarantees.

Fetching Modules : Go can retrieve modules via tags, branches, or commit hashes. When a non‑standard reference is used, Go converts it into a pseudo‑version. Example: go get -d golang.org/x/net@daa7c041 produces the pseudo‑version v0.0.0-20191109021931-daa7c04131f5. Pseudo‑versions have three components: a base version prefix, a UTC timestamp (yyyymmddhhmmss), and a 12‑character commit identifier. The exact format depends on the existing base version (no base version, a pre‑release base, or a final release base).

Ordering rules: pseudo‑versions are higher than their base version but lower than later pseudo‑versions with the same prefix; those sharing a prefix are sorted chronologically.

Additional examples of fetching with pseudo‑versions:

go get -d example.com/mod@master

go list -m -json example.com/mod@abcd1234

The article concludes by summarizing the three core concepts covered—module path, versioning & compatibility principles, and pseudo‑versions—and hints at the next piece, which will dive deeper into Go Modules core concepts such as the go.mod file and version suffixes.