Modules

Canonical guidance

• use go.mod as the declared module boundary
• commit go.mod and go.sum
• keep dependencies explicit and reviewable
• understand major version suffix rules for v2+
• route workspace, replacement, vendoring, and private-module policy questions to dedicated narrower pages

Use when

• starting any modern Go repo
• publishing libraries
• upgrading dependencies

Avoid

• ad hoc dependency management outside modules
• ignoring semantic import versioning for v2+
• treating transitive dependency state as invisible

Preferred pattern

package main

import "example.com/acme/widget/v2"

func main() {
	_ = widget.NewClient()
}

Anti-pattern

• shipping a v2 module at the old import path

Explanation: This anti-pattern is tempting when release pressure is high, but ignoring import versioning breaks consumers in ways tooling cannot smooth over.

Why

• modules are the compatibility and reproducibility contract for Go dependencies