GopherForgeA WORKBENCH FOR GO

Packages, modules and tooling · 3 MIN READ

A local workspace can hide a broken release

Use go.work and replace for development while checking what an independent consumer builds.

A checkout can pass because go.work supplies a sibling module or replace points to a local directory that no consumer has. That success tests the local composition, not the published module. Keep a second path that exercises the version and files a real downstream user receives.

Packages and production tooling · A MAP OF THE IDEA

  1. Local modules
  2. Workspace resolution
  3. Isolated consumer
  4. Published artifact

Useful when

  • Use go.work and replace for development while checking what an independent consumer builds.

Watch out

  • GOWORK=off removes the local workspace composition. That exposes missing published requirements and APIs that only worked through sibling modules or local replacements.

Implementation & operation cost: Fast local iteration needs a separate isolated-consumer check to expose unpublished assumptions before release.

01

See the workspace and overrides

Inspect the active workspace and replacements before comparing two machines. A local replacement changes source selection; a replace line in a dependency is not automatically inherited by its consumers. Avoid committing an absolute workstation path as a release dependency.

bash
go env GOWORK
go work edit -json
go list -m -json all
Read the code

The workspace JSON lists participating module directories; the module listing shows replacements used by the build. Compare these facts before assuming a compiler or operating-system bug.

02

Verify the module on its own

Run checks with GOWORK=off from the module directory and build a small independent consumer using the intended release version. A workspace root with several modules is not equivalent to one module where ./... automatically promises to cover every sibling.

bash
GOWORK=off go mod tidy
GOWORK=off go test ./...
GOWORK=off go list -m all
Read the code

These commands deliberately ignore workspace composition. If the tests now fail, the difference is actionable: a missing requirement, an unpublished API or a dependency that only existed in the workspace.

03

Test migrations from both sides

A coordinated local API change can make producer and consumer pass together while breaking older consumers. Release the producer compatibly, pin the consumer to the released version, then test that combination. Workspace convenience should not replace a compatibility matrix for separately released modules.

TAKE THIS WITH YOU

Use local overrides to iterate quickly, then turn them off to test the module and its published consumer contract independently.

Check your understanding

Why also test with GOWORK=off?

Go to the source

Progress stays in this browser. No account needed.