...
Since CockroachDB is open source, most of the instructions for hacking on CockroachDB live in this repo, cockroachdb/cockroach. You should start by reading CONTRIBUTING.md in full. This file covers how to set up a new development machine to build CockroachDB from source and the basics of the code review workflow.the top level of this section of the wiki.
Then, look at docs/style.md our Go style guide and the Google Go Code Review guide it links to. These are linked to from CONTRIBUTING.mdthe other pages in this wiki, but they're easy to miss. If you haven't written any Go before CockroachDB, you may want to hold off on reviewing the style guide until you've written your first few functions in go.
...
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/azworkergceworker.sh ] most, which spins up a personal Linux VM for you to develop on in the Azure 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 namedvendor, if it exists. See build/README.md for details on how we maintain this folder.
...
It's time to fire up your editor and get to work! The CONTRIBUTING.md document does a other pages on this wiki do a good job of describing the basic development commands you'll need. In short, you'll use make to drive builds.
...
Fix your style violations
First, read docs/style.md againthe Go style guide again, looking for any style violations. It's easier to remember a style rule once you've violated it.
...
Be kind to other developers, including your future self, by splitting large commits. Each commit should represent one logical change to the codebase with a descriptive message that explains the rationale for the change. CONTRIBUTING.md has some advice on writing good commit messages: on On your first PR, it's worth re-reading that section to the Git Commit Messages page to ensure your commit messages follow the guidelines.
...
Protip: often, you'll realize after a bout of hacking that you've actually made n separate changes, but you've got just one big diff since you didn't commit any intermediate work. Explaining how to fix this is out of scope for this guide, but either Git "patch mode" (Google it) or a graphical Git client will take care of it.
See also the "When to submit" section above for advice on when multiple commits should be further split into multiple PRs.
...
GitHub displays the status of the latest TeamCity run at the bottom of every pull request. You can click the "Details" link to get insight into a failed build or view real-time status of an in-progress build. Occasionally, a build will fail because of flaky tests. You can verify by running a new build and seeing if the problem disappears; just hit the "Run" button on the top right of the page GitHub links to queue a new build. Less frequently, TeamCity will entirely fail to notice a PR, and GitHub will display "waiting for status to be reported" forever. The "TeamCity Continuous Integration" wiki page describes how to fix this.
Unfortunately, a full tutorial on TeamCity is outside the scope of this document. Ask your Roachmate for an overview if you're confused, or post specific questions in #teamcity in slack.
That's it! You're done. Sit back and get ready for the impending code review.
...
In this repository in particular, merging a PR means accepting responsibility for maintaining that code for, quite possibly, the lifetime of CockroachDB. To take on that reponsibility, we need to ensure that meets our strict standards for production-ready code.
No one is expected to write perfect code on the first try. That's why we have code reviews in the first place!
...
Probably everyone has at some time had an unpleasant interaction during a code review, and with code reviews being by humans for humans, one or both of these humans could be having a bad day. As if that weren't enough already, text-based communication is fraught with miscommunication. Consider being a minimally nice maintainer), reflect upon mistakes that will inevitably be made, and take inspiration from the constructive and friendly reviews that are the daily staple of our repository.
For more details see Working as a reviewer.
Reviewable
Except for the smallest of PRs, we eschew GitHub reviews in favor of a third-party app called Reviewable. Reviewable has an incredibly dense UI: you could probably master a new musical instrument faster than you could master Reviewable.
...
A list of even more Cockroach jargon lives on this repository's wiki.
Merging
External contributors: you don't need to worry about this section. We'll merge your PR as soon as you've addressed all review feedback!
...
Here's a checklist of action items to keep you sane:
- Developing
...
- Create a GitHub fork of cockroachdb/cockroach
...
- Read through
...
- Submitting your first PR
...
- Push to a feature branch on your personal fork
...
- Verify you've
...
- followed the Go style guide
- 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=reviewerto ask Craig to merge
- Comment
...