Skip to main content
We welcome contributions from the community! Whether you’re fixing bugs, adding features, improving documentation, or helping with testing, your contributions make CockroachDB better.

​
Getting Started

​
Choose Your Project

CockroachDB offers different contribution paths based on your experience and interests:

New Developers

To-Do Apps ProjectBuild a to-do app using CockroachDB with your favorite language/ORM.View Repository →

Go Developers

Core CockroachDBWork on the main CockroachDB codebase. Check out good first issues.Good First Issues →

Kubernetes Enthusiasts

Kubernetes OperatorContribute to the CockroachDB Kubernetes Operator.Operator Issues →

Documentation

Docs & WritingHelp improve CockroachDB documentation.Docs Issues →

​
Development Workflow

1

Join the Community

Join our Community Slack (there’s a dedicated #contributors channel!) to ask questions and connect with other contributors.Please follow our Code of Conduct to help keep the community welcoming.
2

Set Up Your Environment

Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/cockroach.git
cd cockroach
git remote add upstream https://github.com/cockroachdb/cockroach.git
Install dependencies:
./build/bootstrap/bootstrap-debian.sh
3

Find or Create an Issue

Before starting work:
  • Check existing issues or create a new one
  • Comment on the issue to claim it
  • Discuss your approach for larger changes
For significant features or architectural changes, consider writing an RFC first. See the RFC process.
4

Create a Branch

git checkout -b your-feature-branch
Use descriptive branch names like fix-kvserver-leak or add-json-functions.
5

Make Your Changes

Follow the coding guidelines and ensure your changes:
  • Are well-tested
  • Include appropriate comments
  • Follow the style guide
  • Don’t break existing functionality
6

Test Your Changes

Run relevant tests:
# Run tests for affected packages
./dev test pkg/your/package -v

# Run specific test
./dev test pkg/sql -f=TestYourFeature -v
See the Testing Guide for more details.
7

Format Your Code

Use crlfmt (not gofmt):
crlfmt -w -tab 2 your_file.go
CockroachDB uses its own formatter crlfmt that enforces 100-column code lines, 80-column comments, and specific import grouping.
8

Generate Code (if needed)

If you modified protobufs, parsers, or other generated code:
./dev generate go
./dev generate bazel
9

Submit Your Pull Request

Push your branch and create a PR:
git push origin your-feature-branch
In your PR description:
  • Reference the issue number (e.g., “Fixes #12345”)
  • Explain what changed and why
  • Include any relevant context

​
Coding Standards

​
Code Quality Guidelines

CockroachDB is a complex distributed system. Write code with future maintainers in mind:
  • Explain key concepts and abstractions clearly
  • State lifecycles and ownership explicitly
  • Use examples to make code accessible
  • Comments should add depth, not repeat the code
Good Example:
// proposalQuota tracks the maximum number of bytes that can be used by
// in-flight Raft proposals. It ensures bounded memory usage for the
// proposal buffer by blocking proposals when the quota is exhausted.
type proposalQuota struct {
    // ...
}
  • Use crlfmt -w -tab 2 <file>.go for formatting
  • Enforces 100-column code lines
  • 80-column comments
  • CockroachDB-specific import grouping
  • crlfmt accepts one filename at a time
CockroachDB supports rolling upgrades, so:
  • Be mindful of compatibility when changing shared state
  • Consider inter-process communication carefully
  • Review pkg/clusterversion for version handling
  • Test mixed-version scenarios when relevant
  • Write tests for new functionality
  • Update tests when changing behavior
  • Include both unit and integration tests
  • Consider edge cases and failure scenarios
  • Add logic test files for SQL features

​
Commit Message Guidelines

Follow the commit message format used by the project: 
pkg: brief summary of change

Longer explanation of what changed and why. Focus on the "why"
rather than the "what" - the code shows what changed.

Fixes #12345

Release note (category): description of user-facing change
See the wiki for detailed commit message guidelines.

​
Code Review Process

​
What Reviewers Look For

Technical Correctness

  • Logic is sound
  • No race conditions
  • Proper error handling
  • Performance implications

Code Clarity

  • Clear naming
  • Good documentation
  • Accessible to non-experts
  • Examples where helpful

Testing

  • Adequate test coverage
  • Tests are meaningful
  • Edge cases covered
  • No flaky tests

Style & Convention

  • Follows project patterns
  • Properly formatted
  • Minor nits prefixed with “nit:”
  • Consistent with codebase

​
Responding to Reviews

  • Address all comments, even if just to acknowledge
  • Push new commits rather than force-pushing (makes review easier)
  • Mark resolved threads as resolved
  • Ask questions if feedback is unclear
  • Be open to suggestions and alternative approaches

​
Resources

Contributing Wiki

Comprehensive contributor guidelines on the public wiki

Your First PR

Step-by-step guide for first-time contributors

Community Slack

Join #contributors channel for help and discussion

Code of Conduct

Guidelines for community participation

​
Additional Topics

The contributor wiki covers:
  • Repository layout and organization
  • Commenting guidelines and standards
  • How to write release notes
  • Submitting changes for review
  • Using continuous integration (CI)
  • Troubleshooting common issues
  • Performance testing guidelines
  • Documentation standards
And many other practical topics for contributors.

​
Getting Help

If you need assistance:
  1. Check the contributor wiki
  2. Ask in the #contributors Slack channel
  3. Comment on the relevant GitHub issue
  4. Tag reviewers or maintainers for specific questions
We’re here to help make your contribution successful!

Build docs developers (and LLMs) love

Get started for freeTalk to us