...

This document is a long-winded guide to preparing and submitting your first contribution to CockroachDB. It's primarily intended as required reading for new Cockroach Labs engineers, but may prove useful to external contributors too.

The development cycle

At the time of this writing, CockroachDB is several hundred thousand lines of Go code, plus a smattering of C++ and TypeScript. This section is a whirlwind tour of what lives where.

...

Here's what's in each top-level directory in this repository:

• build/ Build support scripts. You'll likely only need to interact with [build/builder.sh]. See "Building on Linux" below.

• c-deps/ Glue to convince our build system to build non-Go dependencies. At the time of writing, "non-Go dependencies" means C or C++ dependencies. The most important of these is RocksDB, our underlying persistent key-value store.

• cloud/kubernetes/ Kubernetes configuration to auto-launch CockroachDB clusters.

• docs/ Documentation for CockroachDB developers. See "Internal documentation" below.

• monitoring/ Configuration to integrate monitoring frameworks, namely Prometheus and Grafana, with CockroachDB. This configuration powers our internal monitoring dashboard as well.

• pkg/ First-party Go code. See "Internal documentation" below for details.

• scripts/ Handy shell scripts that aren't part of the build process. You'll likely interact with scripts/gceworker.sh most, which spins up a personal Linux VM for you to develop on in the GCE cloud.

• vendor/ A Git submodule that contains the right version of our dependent libraries. For many years, the Go answer to dependency management was "write backwards-compatible code." That strategy is as dangerous as it sounds, so since v1.6, Go will automatically load packages in a subdirectory named vendor, if it exists. See build/README.md for details on how we maintain this folder.

...

Besides cockroachdb/cockroach, the cockroachdb GitHub organization is home to several other important open-source components of Cockroach:

• cockroachdb/docs, which houses the code behind our user-facing documentation at cockroachlabs.com/docs. At the time of writing, our stellar docs team handles essentially all documentation.

• cockroachdb/examples-go, which contains small, self-contained Go programs that exercise CockroachDB via the PGWire protocol. You're likely to hear most about block_writer, which writes uniformly random values into a table, and photos, which simulates a more-realistic workload of a photo-sharing site, where some photos and users are orders of magnitude more popular. The other example programs are of a similar scope and purpose, but block_writer and photos are deemed important enough to run constantly against our production clusters.

• cockroachdb/examples-orms, which showcases ORMs a toy API that uses an ORM to prepare its responses in several different languages.

...

The one exception to this rule is docs/tech-notes/contexts.md. It's worth learning why so many of our function signatures take a context as their first parameter, like so:

func doOperation(ctx context.Context, ...)

Otherwise, plumbing contexts everywhere will feel like a chore with no upsides.

...

To produce a cockroach binary:

$ make build

To run all the tests in ./pkg/rest/of/path:

$ make test PKG=./pkg/rest/of/path

Is there a Go debugger?

Yes! It's called delve.

...

Then, run our suite of linters:

$ make lint

This is not a fast command. On my machine, at the time of writing, it takes about a full minute to run. You can instead run

$ make lintshort

which clocks in at about 30s by omitting the slowest linters.

...

Nearly everything you're tempted to put in a PR description belongs in a Git commit message. (As an extension, nearly everything you put in a commit message belongs in code comments too.)

...

Reviewers may also have comments about subjective matters, for example what code presentation should be considered idiomatic. When in doubt, if the approach suggested by the reviewer doesn't change functionality, it may be a learning opportunity to follow the suggestion—if the reviewer cared to give the suggestion, probably someone else would trip up in the same way too. However, remember that a review is also a two-way discussion and you should feel free to ask your own questions to the reviewer, ask them to motivate their suggestions, and you can also weigh their considerations against your own. Sometimes, an appropriate resolution is to copy a summary of a conversation during the review into a comment inside the source code.

Once you've accumulated a set of changes you need to make to address review feedback, it's time to force-push a new revision. Be sure to amend your prior commits—you don't want to tack on a bunch of fixup commits to address review feedback. If you've split your PR into multiple commits, it can be tricky to ensure your review feedback changes make it into the right commit. A tutorial on how to do so is outside the scope of this document, but the magic keywords to Google for are "git interactive rebase."

...

These are the acronyms you'll frequently encounter during code reviews.

• CR, "code review"

• PR, "pull request"—you probably knew that one.

• PTAL, "please take another look"

• RFAL, "ready for another look"—as in, I made some changes, PTAL.

• LGTM, "looks good to me"—i.e., ship it!

• Image ModifiedImage Modified

  , "science dog"—i.e., I have no idea what this code does.

• TF[YT]R, "thanks for your/the review"

A list of even more Cockroach jargon lives on this repository's wiki.

...

Here's a checklist of action items to keep you sane:

•  Developing
•  Create a GitHub fork of cockroachdb/cockroach
•  Read through the contributor guide in this wiki
•  Submitting your first PR
•  Push to a feature branch on your personal fork
•  Verify you've followed the Go (Golang) coding guidelines
•  Verify you've read What is a Good CockroachDB PR
•  Verify you've read Submitting your contribution
•  Ensure files you've added, if any, have a license block
•  Run make check
•  Split your change into logical commits with good messages
•  Addressing feedback
•  Amend the appropriate commits and force-push
•  Respond to all feedback with "Done" or a counterargument
•  Merging
•  Comment bors r=reviewer to ask Craig to merge