Dependency Resolution

Decide on egress policy, availability and ownership. The public mirror is free, durable and highly available but puts every build on the public internet; an internal mirror buys allowlisting and one credential boundary, and becomes a company-wide single point of failure.

Publishing is a support commitment, not a packaging step. Decide on who else genuinely needs it, whether you will honour a stable import path for years, and whether keeping it internal or copying the code is cheaper.

Weigh what a /v2 costs everyone else. Because consumers must rewrite import paths by hand and no upgrade command crosses a major, a v2 reaches nobody automatically and you maintain two trees. Cut one only when the break cannot be made additive.

Decide by asking who bears each cost. Committing the vendor directory buys builds that need no network and puts every dependency change into code review, at the price of huge diffs, merge conflicts and a second tree to keep in sync with go.mod.

Commit go.work only when every directory it uses lives in this repository and every developer wants that same set, and only as a convenience no pipeline depends on. Default to one module unless parts genuinely need independent release lines.

An exclude line in the main module's go.mod makes the go command act as if that version of that module does not exist. Requirements on it move up to the next higher available version, and the build fails if none exists.

Prefix the Git tag with the module's directory path relative to the repository root: cli/v1.2.0 publishes the module whose go.mod sits in ./cli. A plain v1.2.0 tag publishes only the root module.

Two layouts work. Put v2 in a v2/ subdirectory with its own go.mod whose module line ends in /v2, or keep it on a branch whose root go.mod ends in /v2. Either way the module's own imports must gain /v2.

go work sync computes one dependency version list for the whole workspace, then writes those selected versions back into the go.mod of each module the workspace uses. It raises requirements a module already declares; it does not add new ones.

By default the go command does not fail: it downloads and re-executes with a newer Go toolchain that satisfies the go.mod requirement. Setting GOTOOLCHAIN=local disables that, and the command then refuses with an error naming the required and running versions.

GOMODCACHE holds every downloaded module version, extracted read-only, plus the raw files as fetched. Clearing it forces a fresh download: the right fix for a corrupted local cache, and no fix for a checksum mismatch.

Other modules move too. Because a selected version is the maximum of stated minimums, the go command must also downgrade or drop any module whose own go.mod requires a higher version of your target, and it never upgrades anything to compensate.

Run patch-only upgrades on a frequent schedule so diffs stay reviewable, take minor upgrades deliberately per service before a release, and let any engineer pin a transitive module upward under an advisory, provided the pin is recorded and revisited later.