shepherdjerred/monorepo/go-helper

Go Helper

Use the module's declared Go language version, propagate errors, keep goroutine ownership explicit, and run the repository's real verification commands. Distinguish read-only module checks from operations that edit files or fetch dependencies.

Current baseline

Verified 2026-08-03: current stable is Go 1.26.5.

go version
go env GOTOOLCHAIN GOVERSION

Go 1.26 added expression-valued new, the default Green Tea garbage collector, lower cgo overhead, crypto/hpke, and other library/tool changes. JSON v2 remains experimental behind GOEXPERIMENT=jsonv2; SIMD work is experimental and platform-specific.

The go directive is a strict minimum language/toolchain version. toolchain suggests a toolchain for the main module. Module-version boundaries also control behavior such as Go 1.22 loop variables and Go 1.23 timer channels.

Read references/releases.md for the 44-page research ledger. Read references/modules-and-tooling.md for module, workspace, toolchain, lint, and dependency operations. Read references/testing-and-performance.md for tests, fuzzing, races, synctest, traces, profiles, and PGO. Read references/patterns-and-security.md for errors, goroutines, HTTP, paths, logging, randomness, and vulnerability checks.

Command authority

Read-only or check-oriented commands:

go version
go env
go list ./...
go test ./...
go test -race ./...
go vet ./...
go mod verify
go mod tidy -diff
go work edit -json

go mod tidy edits go.mod and go.sum. Dependency and download commands can mutate caches and involve network state. Review their effect instead of labeling them read-only.

Focused verification

Use the package's actual task when one exists. A generic Go project baseline is:

go test ./...
go test -race ./...
go vet ./...
go mod tidy -diff

Run the repository-pinned golangci-lint command if configured. Do not prescribe a fixed number of linters; its catalog and defaults are versioned.

Modules and toolchains

module example.com/project
 
go 1.26

The go line is the minimum required version and selects language behavior. GOTOOLCHAIN controls whether the bundled, PATH, or downloadable toolchain is selected.

Use go get for dependency changes and go mod tidy to reconcile the module graph. Review both go.mod and go.sum. Avoid a broad go get -u ./...; upgrade an intentional set, read release notes, and verify the resulting graph.

For a non-mutating tidy check:

go mod tidy -diff

Errors

Return errors with context and preserve identity with %w when callers may inspect them:

func load(path string) ([]byte, error) {
	data, err := os.ReadFile(path)
	if err != nil {
		return nil, fmt.Errorf("read %q: %w", path, err)
	}
	return data, nil
}

Do not discard Close, ReadAll, Write, trace, or server errors when failure can affect correctness. For cleanup whose error matters, call and return it explicitly rather than relying only on defer.

Goroutine ownership

Every goroutine needs a lifecycle: completion, cancellation, or a process-long owner. Thread context.Context through request-scoped operations; never store it in a long-lived struct solely for convenience.

Prefer errgroup or an equivalent structured owner when sibling failure should cancel work. Bound concurrency and preserve output ordering when the contract requires it.

Tests and benchmarks

Go 1.25 stabilized testing/synctest; the stable API is synctest.Test(t, func(t *testing.T) { ... }) plus synctest.Wait(). Fake time advances only when goroutines in the bubble are durably blocked.

Use B.Loop() for current benchmarks. Avoid exact universal race-detector or benchmark overhead claims. The race detector only finds races executed on a supported platform.

Fuzz failures are stored at testdata/fuzz/FuzzName/<hash>. Keep them as regression corpus entries.

Modern APIs

• Iterator functions and iter.Seq / Seq2 support range-over-function patterns. Do not yield after yield returns false.
• maps and slices expose iterator-producing and consuming helpers.
• unique.Make canonicalizes comparable values into handles.
• math/rand/v2 is non-cryptographic randomness.
• os.Root confines supported file operations against symlink path escapes.
• runtime/trace.FlightRecorder provides bounded recent trace data; check Start and WriteTo errors and call Stop.
• crypto/hpke implements the RFC 9180 DHKEM suites. Hybrid post-quantum KEMs require a separate specification; use protocol-specific expertise before designing cryptography.

HTTP and profiling

Check every server error. Bind diagnostic endpoints to an operator-only interface and never expose net/http/pprof unauthenticated to the public network.

Block and mutex profiles require nonzero profiling rates. CPU, heap, goroutine, block, and mutex profiles answer different questions.

Representative production CPU profiles can drive PGO through default.pgo. A profile must match the workload; do not treat PGO as a universal speed switch.

Security

• Use crypto/rand for secrets; math/rand/v2 is for non-security randomness.
• Use os.Root or equivalent confinement for untrusted relative paths.
• Keep private module configuration in GOPRIVATE, GONOPROXY, and GONOSUMDB as appropriate. GONOSUMCHECK does not exist.
• In source mode, run govulncheck for known vulnerabilities reachable from application call paths. Binary mode reports vulnerable symbols but does not reconstruct those call paths.
• Treat imported pprof handlers, cgo, templates, archive extraction, and subprocess arguments as security boundaries.
• Use structured log/slog fields and never log secrets.

Review checklist

• Verify Go stable, the module go line, and selected toolchain.
• Use go mod tidy -diff for a non-writing module check.
• Review intentional dependency changes and both module files.
• Propagate meaningful errors, including cleanup and server failures.
• Give every goroutine an owner and cancellation path.
• Use exact tests, current synctest, correct fuzz corpus paths, and workload-qualified performance claims.
• Keep profiling endpoints private and check trace/profile errors.
• Use current golangci-lint v2 configuration and canonical gopls setting names.
• Separate experimental JSON v2 and SIMD behavior from stable defaults.
• Run govulncheck and use cryptographic randomness for secrets.