Development workflow

The Go project uses Gerrit for code review. The flow is clone → branch → commit → mail → review → land. Every step has a project-specific quirk; this page walks through them.

One-time setup

# Install the Gerrit helper subcommand:
go install golang.org/x/review/git-codereview@latest

# Clone from the canonical repo (NOT the GitHub mirror):
git clone https://go.googlesource.com/go
cd go

# Set your Git author info to match the email you used on the CLA.
git config user.email you@example.com
git config user.name "Your Name"

Then open https://go.dev/doc/contribute#config_git_auth and follow the steps to set up Gerrit cookie auth via https://go.googlesource.com/new-password.

Branches and CLs

Go does not use a feature-branch-per-PR model. Instead:

• Each change is a single commit on its own local branch.
• That commit becomes a Gerrit "Change-Lis" (CL) when you mail it.
• Subsequent revisions amend the same commit (git codereview change) and re-mail.
• When the CL is Code-Review +2 and TryBot +1, a maintainer pushes the submit button on Gerrit, which lands the change on master with the same Change-Id.

Day-to-day:

git codereview change my-fix       # create branch + start commit
# ... edit code ...
git add -A
git codereview change              # amend the existing commit
git codereview mail                # send the CL to Gerrit for review
# ... reviewer comments come in ...
git codereview change              # amend with replies + edits
git codereview mail                # re-send (creates a new patch set)

A CL always has a Change-Id: trailer in the commit message. git codereview adds it automatically; do not remove or change it across revisions.

Commit message format

Strict and uniform across the codebase:

pkg/path: short, imperative summary (≤ 72 chars)

Longer paragraph explaining what changed and why. Wrap to ~76
characters. Include benchmarks or examples when relevant.

For #12345
Fixes #12345

Conventions:

• The prefix pkg/path: matches the import path of the most affected package, e.g., runtime:, cmd/compile:, net/http:. Use a comma-separated list for multi-package changes (runtime, syscall:).
• The summary is imperative mood (add, fix, avoid), lowercase, no trailing period.
• The body is wrapped at ~76 columns and explains why. Reviewers will reject short or empty messages.
• Issue references go in trailers: Fixes #N closes the issue; Updates #N references it; For #N is older alternate phrasing still seen.

What git codereview does for you

Beyond the helpers above, it enforces a few invariants:

• git codereview hooks installs a pre-commit hook that runs gofmt, checks for stray trailing whitespace, etc.
• git codereview mail ensures only one commit is being mailed (refuses if the branch contains multiple commits).
• git codereview rebase-work updates your branch onto a fresh master while preserving the Change-Id.
• git codereview submit is the submit button for committers; mortals do not use it.

Asking for review

Add reviewers in Gerrit's web UI or by adding R=name@golang.org to the commit message before mailing. The maintainers list per directory is informally tracked in CODEOWNERS-equivalent notes maintained by the Go team; see issue tracker labels and the per-package OWNERS conventions in doc/contribute.md.

For new contributors, leaving reviewers blank is fine — the Gerrit dashboard auto-assigns based on the touched files.

TryBot runs

Before merge, every CL must pass the trybots — a fleet of builders that compiles and tests on dozens of OS/arch combinations:

TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

To trigger a run, set Run-TryBot +1 in Gerrit (or comment Run-TryBot+1). For most CLs, only a maintainer can do this. New contributors should ask in the CL after their first round of +1 review.

Submitting

Only Go committers can press Submit. The process is:

1. CL has at least one Code-Review +2.
2. TryBot-Result: +1 is present (passing trybots).
3. Run-TryBot and Code-Review votes are stable.
4. Submit. Gerrit creates the merge commit on master and replies to GitHub mirror watchers.

Backports

Bug fixes targeted at released branches go through gopls-style minor releases. Open the issue with the right milestone, then mail the cherry-picked CL to the appropriate release-branch.go1.N Gerrit branch. The "Backport" label on the issue tracks proposal/approval.

Where to read next

• Testing — what to run locally before mailing.
• Patterns and conventions — what reviewers will look for.
• Debugging — diagnostics for when something breaks.