Permalink
May 27, 2014
Sep 7, 2017
Sep 26, 2017
Oct 15, 2017
Sep 26, 2017
Oct 22, 2017
Sep 26, 2017
Sep 26, 2017
Sep 26, 2017
Mar 9, 2017
Mar 9, 2017
Jan 24, 2018
Jan 25, 2018
Jan 24, 2018
Sep 26, 2017
Sep 26, 2017
May 27, 2014
Mar 22, 2017
May 27, 2014
Apr 3, 2017
May 27, 2014
Jul 31, 2016
May 27, 2014
Sep 26, 2017
Sep 26, 2017
Mar 28, 2018
Sep 26, 2017
Jan 17, 2018
Sep 26, 2017
Oct 28, 2015
Newer
100644
224 lines (174 sloc)
9.3 KB
1
# Contributing to Cockroach
2
3
- [Prerequisites](#prerequisites)
4
- [Getting and Building](#getting-and-building)
5
- [Style Guide](#style-guide)
12
Before you start contributing, review these [basic
13
guidelines](https://www.cockroachlabs.com/docs/stable/contribute-to-cockroachdb.html)
14
on finding a project, determining its complexity, and learning what to
15
expect in your collaboration with the Cockroach Labs team.
17
If you *really* want to dig deep into our processes and mindset, you may also
18
want to peruse our extensive [first PR guide], which is part of our on-boarding for
19
new engineers.
20
24
25
- Either a working Docker install able to run GNU/Linux binaries
26
(e.g. Docker on Linux, macOS, Windows), so you can reuse our
27
pre-populated Docker image with all necessary development
28
dependencies; or
29
30
- The tools needed to build CockroachDB from scratch:
31
32
- A C++ compiler that supports C++11. Note that GCC prior to 6.0 doesn't
33
work due to https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48891
34
- The standard C/C++ development headers on your system.
35
- On GNU/Linux, the terminfo development libraries, which may be
36
part of a ncurses development package (e.g. `libtinfo-dev` on
37
Debian/Ubuntu, but `ncurses-devel` on CentOS).
38
- A Go environment with a recent 64-bit version of the toolchain. Note that
39
the Makefile enforces the specific version required, as it is updated
40
frequently.
41
- Git 1.9+
42
- Bash (4+ is preferred)
43
- GNU Make (3.81+ is known to work)
44
- CMake 3.1+
45
- Autoconf 2.68+
59
If you wish to reuse our builder image instead of installing all the
60
dependencies manually, prefix the `make` command with
61
`build/builder.sh`; for example `build/builder.sh make build`.
62
63
Note that the first time you run `make`, it can take some time to
64
download and install various dependencies. After running `make build`,
65
the `cockroach` executable will be in your current directory and can
66
be run as shown in the [README](README.md).
70
- The default binary contains core open-source functionally covered by
71
the Apache License 2 (APL2) and enterprise functionality covered by
72
the CockroachDB Community License (CCL). To build a pure open-source
73
(APL2) version excluding enterprise functionality, use `make
74
buildoss`. See this [blog post] for more details.
75
76
[blog post]: https://www.cockroachlabs.com/blog/how-were-building-a-business-to-last/
80
- To add or update a Go dependency:
81
- See [`build/README.md`](build/README.md) for details on adding or updating
82
dependencies.
92
When you're ready to commit, be sure to write a Good Commit Message™.
93
94
Our commit message guidelines are detailed here:
95
https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages
96
97
In summary (the wiki page details the rationales and provides further suggestions):
98
- Keep in mind who reads: think of the reviewer, think of the release notes
99
- [Separate subject from body with a blank line](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-title)
100
- [Use the body to explain *what* and *why* vs. *how*](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-description)
101
- [Prefix the subject line with the affected package/area](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-title)
102
- [Include a release note annotation](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#release-notes), in the right position
103
- [Use the imperative mood in the subject line](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-title)
104
- [Keep the commit title concise but information-rich](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-title)
105
- [Wrap the body at some consistent width under 100 characters](https://github.com/cockroachdb/cockroach/wiki/Git-Commit-Messages#commit-description)
109
- All contributors need to sign the [Contributor License
110
Agreement](https://cla-assistant.io/cockroachdb/cockroach).
112
- Create a local feature branch to do work on, ideally on one thing at
113
a time. If you are working on your own fork, see [this
114
tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
115
on forking in Go, which ensures that Go import paths will be
116
correct.
121
136
# Run a specific sql logic subtest
137
make test PKG=./pkg/sql TESTS='TestLogic$$/select$$'
141
142
Logs are disabled during tests by default. To enable them, include
143
`TESTFLAGS="-v -show-logs"` as an argument the test command:
144
145
```shell
146
make test ... TESTFLAGS="-v -show-logs"
147
```
148
156
158
and contain a substantial (but not overwhelming) unit of work. You may also
159
want to `git fetch origin` and run
163
168
- Then [create a pull request using GitHub’s
169
UI](https://help.github.com/articles/creating-a-pull-request). If
170
you know of another GitHub user particularly suited to reviewing
171
your pull request, be sure to mention them in the pull request
172
body. If you possess the necessary GitHub privileges, please also
173
[assign them to the pull request using GitHub's
174
UI](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/).
177
- Address test failures and feedback by amending your commits. If your
178
change contains multiple commits, address each piece of feedback by
179
amending that commit to which the particular feedback is aimed. Wait
180
(or ask) for new feedback on those commits if they are not
181
straightforward. An `LGTM` ("looks good to me") by someone qualified
182
is usually posted when you're free to go ahead and merge. Most new
183
contributors aren't allowed to merge themselves; in that case, we'll
184
do it for you.
186
- Direct merges using GitHub's "big green button" are avoided. Instead, we use
187
[bors-ng](https://bors.tech/documentation/) to manage our merges to prevent
188
"merge skew". When you're ready to merge, add a comment to your PR of the
189
form `bors r+`. Craig (our Bors bot)
190
will run CI on your changes, and if it passes, merge them. For more
191
information, see [the wiki](https://github.com/cockroachdb/cockroach/wiki/Bors-merge-bot).
192
197
- the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
198
at `/debug/requests`. It has a breakdown of the recent traced
199
requests, in particularly slow ones. Two families are traced: `node`
200
and `coord`, the former (and likely more interesting one) containing
201
what happens inside of `Node`/`Store`/`Replica` and the other inside
202
of the coordinator (`TxnCoordSender`).
203
- [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
204
other things) heap and cpu profiles; [this wiki page](https://github.com/cockroachdb/cockroach/wiki/pprof)
205
gives an overview and walks you through using it to profile Cockroach.
206
[This golang blog post](http://blog.golang.org/profiling-go-programs)
207
explains it extremely well and [this one by Dmitry
208
Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
215
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
216
```
217