Appendix C-Contributing to Go: A Playbook¶

Most engineers never contribute to a language. The barrier is procedural ("how does Gerrit work?") more than technical. This appendix is the on-ramp.

C.1 Mental Model¶

The Go project ("golang/go") is a single repository containing the compiler, the runtime, the standard library, the linker, and most of the toolchain. It is mirrored to GitHub for visibility, but the primary development happens at go-review.googlesource.com using Gerrit (not GitHub PRs).

Three implications: 1. You file changes as CLs (changelists) in Gerrit, not PRs. 2. Reviewers leave inline comments and a numeric vote (-2..+2). +2 from a maintainer is required to merge. 3. The maintainer set is small and prioritizes correctness over speed. A two-week review cycle is normal; a six-month cycle is not unheard of.

C.2 The Pipeline, in 30 Seconds¶

Source (.go)
  │ Lexer ── tokens
  │ Parser ── AST  (cmd/compile/internal/syntax)
  │ Type checker ── typed AST  (cmd/compile/internal/types2)
  │ IR construction (cmd/compile/internal/ir, ssagen)
  │ SSA  (cmd/compile/internal/ssa)
  │ SSA optimizations (rules/*.rules)
  │ Lowering to architecture-specific SSA
  │ Code generation
  │ Object file (.o)
  │
  │ Linker (cmd/link)-combines objects + runtime
  ▼
Executable

Then at runtime, the executable starts in runtime/asm_*.s → runtime.rt0_go → scheduler bootstrap → runtime.main → user main.

C.3 Setting Up¶

git clone https://go.googlesource.com/go
cd go/src
./make.bash      # builds the toolchain (~3-5 min)
./run.bash       # full test suite (~20 min)

The new toolchain is at ../bin/go. Use it for testing your changes:

../bin/go test -run TestSomething ./...

For Gerrit, install git-codereview:

go install golang.org/x/review/git-codereview@latest
git config alias.change "codereview change"
git config alias.mail "codereview mail"
git config alias.sync "codereview sync"

Sign the CLA at cla.developers.google.com (individual or corporate). Without it, no CL can merge.

C.4 Where the Easy Wins Are¶

In rough order of difficulty:

C.4.1 Documentation fixes¶

Typos, unclear sentences, missing examples in stdlib godoc. Search the issue tracker for Documentation label.
Touch the .go file's doc comment, send a CL. ~10 lines, ~1-week review.

C.4.2 Stdlib bug fixes¶

Look for NeedsFix + help wanted labels. The time, net/http, encoding/*, database/sql packages have a steady flow of small bugs.
Reproduce, write a minimal failing test, fix, send.

C.4.3 New stdlib examples¶

Many functions lack ExampleX testable examples. These render in godoc and are doubly useful as tests.
Trivially good first contribution.

C.4.4 New `go vet` analyzers¶

cmd/vet is small and well-organized. Adding a new analyzer for a recurring bug pattern (with rationale) is a tractable medium contribution.

C.4.5 Compiler diagnostics¶

"Why is this error message confusing?" issues are tagged. Improving cmd/compile/internal/types2's error wording is high-impact and well-bounded.

C.4.6 Compiler optimizations¶

SSA peephole rules in cmd/compile/internal/ssa/_gen/*.rules. Each rule is a pattern → replacement transformation, tested via assembly tests.
Higher bar but still single-CL-sized contributions exist.

C.4.7 Don't start here (yet)¶

The runtime scheduler proper (runtime/proc.go).
The garbage collector (runtime/mgc.go).
The linker.
Anything involving language semantics (proposals → go/proposal repo, separate process, ~year-scale).

C.5 The First-CL Workflow¶

Find an issue. Comment to claim it (no @bot mechanism like rust-bot; just be polite and indicate you're working on it).
Branch from master:
```
git sync
git change <branch-name>
```

Make changes. Run:

../bin/go vet ./...
../bin/go test -short ./...
gofmt -l -d .

Commit with a Go-style commit message:

net/http: fix Server.Shutdown deadlock when called from request handler

Previously, calling Server.Shutdown from within an active request
handler would deadlock because [...].

Fixes #12345

First line: package: short description. Body: rationale and any non-obvious context. Trailer: Fixes #N if applicable.

Mail the CL:
```
git mail
```
This pushes to Gerrit and creates a review thread.
Address review. Reviewers comment inline. Each round: amend the existing commit (do NOT create new commits-git change --amend is the workflow), git mail again. The CL gets new patch sets.
+2 from a maintainer + +1 from the trybots → merged. Your name is in the commit log.

C.6 The Go Source Reading Map¶

When the compiler/runtime is opaque, these are the highest-yield reads:

File	What it teaches
`runtime/runtime2.go`	The data model: `g`, `m`, `p`, `schedt`, `hchan`, `mutex`. Reference.
`runtime/proc.go`	The scheduler. `schedule`, `findrunnable`, `newproc`, `gopark`.
`runtime/mgc.go`	GC entry points and pacing.
`runtime/mbarrier.go`	The write barrier.
`runtime/malloc.go`	Allocator (mcache → mcentral → mheap).
`runtime/chan.go`	Channel internals.
`runtime/iface.go`	Interface dispatch and `itab` cache.
`runtime/select.go`	`select` semantics (subtle; read slowly).
`runtime/preempt.go`	Async preemption mechanism.
`runtime/netpoll.go`	epoll/kqueue/IOCP integration.
`cmd/compile/internal/escape/escape.go`	Escape analysis.
`cmd/compile/internal/ssa/`	SSA IR, optimization passes.

Read in order: runtime2.go → proc.go → chan.go → iface.go → mgc.go → malloc.go → escape analysis → SSA. Allow weeks, not days.

C.7 Adjacent Targets if `golang/go` Is Too Heavy¶

golangci-lint-Active, friendly, fast review. Add a linter, fix a false positive.
staticcheck-Higher bar than golangci-lint, but smaller surface and Dominik Honnef is a thoughtful reviewer.
golang.org/x/* repos-x/tools, x/sync, x/exp. Same Gerrit workflow as golang/go, but sometimes faster review.
gopls-language server. High-impact contributions; AST/types fluency from week 14 directly applies.
prometheus/client_golang, grpc/grpc-go, etcd-io/etcd-large Go projects with active maintainers and well-documented contribution flows. A merged PR signals real-world Go fluency.

C.8 Calibration¶

A reasonable goal for a curriculum graduate:

By end of week 23: a CL open against golang/go (a stdlib doc fix or small bug fix) or a PR against a well-known Go project.
By end of capstone: that CL/PR merged.
6 months post-curriculum: a non-trivial CL-a stdlib API addition, a go vet analyzer, a compiler diagnostic improvement.

These are realistic timelines. The maintainers prioritize stability. Do not be discouraged by a four-week review cycle; that is healthy.