Versioning & Minimal Version Selection

Semantic Versioning (SemVer)

Go modules use vMAJOR.MINOR.PATCH (the v prefix is required):

MAJOR: Breaking changes to the public API
MINOR: Backward-compatible new functionality
PATCH: Backward-compatible bug fixes

Stability Rules

Version	Stability
`v0.x.x`	Unstable — no compatibility guarantees
`v1.x.x`+	Stable — backward-compatible within major
Pre-release	Unstable (e.g., `v1.5.0-beta.1`)

Major Version Suffix Rule

For v2 and above, the module path must include a /vN suffix. This is Go's import compatibility rule — different major versions are treated as entirely separate modules, allowing them to coexist in the same build:

// go.mod
module github.com/example/pkg/v2

// Import in code
import "github.com/example/pkg/v2/subpkg"

Tags: v2.0.0, v2.1.0, etc. The v0 and v1 versions have no suffix.

Special Cases

Pseudo-versions: For untagged commits — v0.0.0-20210101120000-abcdef123456 (base version + timestamp + commit hash)
+incompatible: Marks v2+ modules that have not adopted the /vN path convention
gopkg.in: Always uses a version suffix with a dot — gopkg.in/yaml.v3

Minimal Version Selection (MVS)

Go's dependency resolution algorithm is fundamentally different from npm, pip, or cargo.

How It Works

Most package managers select the latest compatible version of each dependency. Go does the opposite: it selects the minimum version that satisfies all requirements. If module A requires pkg@v1.2.0 and module B requires pkg@v1.3.0, MVS selects v1.3.0 — the highest minimum required, not the latest available.

Why This Design

Deterministic without a lock file: Given the same go.mod inputs, MVS always produces the same build list. go.sum is just integrity verification.
High fidelity: Builds closely match what module authors tested against, since the nearest compatible version is selected rather than the latest.
No solver needed: The algorithm is simple graph traversal (under 50 lines of code), not an NP-hard constraint satisfaction problem.
Reproducible across machines: No "works on my machine" from different lock file states.

Upgrades and Downgrades

Upgrade: go get pkg@v1.5.0 adds an edge to v1.5.0 in the module graph and reruns MVS. Only the minimum necessary changes propagate.
Downgrade: go get pkg@v1.2.0 removes all versions above v1.2.0 from the graph, then walks backward to find the latest remaining versions of affected dependencies.

2.7 KiB Raw Permalink Blame History