How to contribute

This section is the working contributor's quick reference for the CockroachDB repo. The canonical docs are CONTRIBUTING.md, docs/style.md, docs/commits-and-prs.md, and docs/backporting.md. CockroachDB's external-contributor wiki at https://wiki.crdb.io/ goes deeper.

Picking up work

• Browse the good-first-issue list.
• Internal teams own subsystems via .github/CODEOWNERS and TEAMS.yaml. The repo's maintainers page maps the major subsystems to teams.
• Trivial spelling/wording-only changes to comments and error messages are usually rejected — they cause merge conflicts in active branches.

Sign before you push

CockroachDB requires a signed Contributor License Agreement. The CLA bot will block merges otherwise.

The development cycle

1. Branch from master.
2. Make your changes. Run crlfmt -w -tab 2 path/to/file.go for every Go file you touch — see patterns and conventions.
3. Run ./dev generate for any code-gen impacted (protobuf, opt rules, mock interfaces). See tooling.
4. Build and test the affected packages: ./dev test pkg/your/package. See testing.
5. Lint: ./dev lint --short.
6. Commit with the CRDB commit-message conventions. The commit message — not the PR description — is the primary record. Include Release note (...) annotations.
7. Push and open a PR.
8. Land via /trunk merge (CockroachDB's merge bot, craig). Don't use the green merge button — it bypasses required CI gates.

Code review expectations

As an author:

• Most reviewers respond within hours for small PRs and within a business day for larger ones.
• Expect comments on test coverage, idiomatic Go (see docs/style.md), and minor nits prefixed nit:.
• Watch the "Files" tab of .github/CODEOWNERS changes — GitHub's preview surfaces lint errors.

As a reviewer:

• Discuss design before details for large PRs; if you foresee multiple passes, say so up front.
• Check that user-facing changes carry release notes and that backwards-incompatible behavior is gated on a cluster version.
• Prefer nit:-prefixed style comments over blocking on style.

Backporting

CockroachDB maintains several active release lines (v25.4.x, v26.1.x, v26.2.x at the time of writing). Bug fixes that should reach a release branch are backported manually following docs/backporting.md. There is internal tooling for opening backport PRs, but it is not required.

Sub-pages

• Development workflow — branching, generated code, build/test commands, environment variables.
• Testing — Go unit tests, datadriven, logictest, roachtest, stress, race.
• Debugging — logs, tracing, common failure modes.
• Patterns and conventions — error handling, naming, comments, cluster-version gating.
• Tooling — Bazel/./dev, code generation, crlfmt, lint, vet, telemetry of dev tooling.