CodeVetter · Repo Unpack · Contributor handoff
golang/go
Working rules: never build inside a pristine checkout without a bootstrap Go; run tests via the built tree's ../bin/go, not a system go. The safe edit boundary is: stdlib packages are ordinary Go code, but runtime, compiler SSA tables, api/ manifests, and cmd/go internals have hard invariants and generated files. Always read the file's package comment first — cmd/dist, runtime/proc.go, mgc.go and gc/main.go carry long design comments that encode the actual contract. After edits, run the package's own tests plus cmd/internal/testdir for anything touching the toolchain.
- Build: 'cd src && ./make.bash' (needs GOROOT_BOOTSTRAP >= Go 1.26.0); full validation: ./all.bash which runs make.bash + run.bash; test-only: 'cd src && ./run.bash' or '../bin/go test cmd/internal/testdir -run=Test/<file>'.
- Read first for any toolchain change: src/cmd/go/main.go (command wiring), src/cmd/go/internal/base/base.go (Command contract), src/cmd/go/internal/work/exec.go (build engine), src/cmd/go/internal/load/pkg.go (Package model), src/cmd/go/internal/modload/init.go (module state).
- Read first for compiler work: src/cmd/compile/main.go, src/cmd/compile/internal/gc/main.go (the phase ordering is the file), src/cmd/compile/internal/ssacompile/compile.go (pass table); for runtime work: src/runtime/proc.go and src/runtime/mgc.go headers are mandatory.
- make.bash explicitly forbids new code after the bootstrap call — additions belong in cmd/dist's cmdbootstrap so all three shell variants (make.bash/make.bat/make.rc) stay minimal.
- api/go1*.txt files are frozen once shipped; only api/next/* is mutable and each new line needs a '#nnnnn' proposal issue annotation; except.txt lists permitted exceptions.
- PackagePublic in load/pkg.go is a public API surface ('okay to add fields, but not to change or remove existing ones. Keep in sync with ../list/list.go') — renaming a field breaks 'go list -json' consumers.
- Generated-code traps: cmd/go/internal/test/flagdefs.go is produced by genflags.go; ssacompile/opGen.go and rewrite tables are generated; dist's writeGeneratedFiles produces version/config files — regenerate rather than hand-editing.
- Error conventions: go-command code uses base.Fatalf/base.Errorf (exit status via base.SetExitStatus + base.Exit with atExitFuncs); runtime code uses throw() for invariant violations and fatal() for startup failures — do not mix.
- GOPATH/GOROOT hygiene: go command fatals on GOPATH entries starting with '~' or relative paths and warns when GOPATH==GOROOT; tests run with GOPATH=/nonexist-gopath so code must not depend on a real GOPATH.
- The -C flag must be first on the command line and is stripped by handleChdirFlag before dispatch; toolchain re-exec relies on this — new pre-dispatch logic must not break the ordering.
- Vendored deps: std module vendors golang.org/x/{crypto,net,sys,text} under src/vendor; cmd module has its own vendor tree incl. x/tools and x/mod — update via normal module workflow then re-vendor; go.mod 'go 1.28' means only language features ≤1.28 are usable.
- Contributions go through Gerrit (codereview.cfg), not GitHub PRs; security issues go to security@golang.org per CONTRIBUTING.md; 'go bug' is the recommended issue-filing path.
- internal/ packages are import-restricted by the compiler itself (enforced in load/internal), so new shared helpers for cmd tools belong under src/cmd/internal; std internals under src/internal. (inferred)