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
Sep 26, 2017
Sep 26, 2017
Mar 9, 2017
Sep 26, 2017
Sep 26, 2017
May 27, 2014
Mar 22, 2017
May 27, 2014
Apr 3, 2017
Aug 18, 2016
Oct 20, 2017
May 27, 2014
Jul 31, 2016
May 27, 2014
Sep 26, 2017
Sep 26, 2017
Sep 26, 2017
Oct 28, 2015
Newer
100644
228 lines (179 sloc)
9.15 KB
1
# Contributing to Cockroach
2
3
- [Prerequisites](#prerequisites)
4
- [Getting and Building](#getting-and-building)
5
- [Style Guide](#style-guide)
6
- [Code Review Workflow](#code-review-workflow)
7
- [Debugging](#debugging)
8
11
Before you start contributing, review these [basic
12
guidelines](https://www.cockroachlabs.com/docs/stable/contribute-to-cockroachdb.html)
13
on finding a project, determining its complexity, and learning what to
14
expect in your collaboration with the Cockroach Labs team.
16
If you *really* want to dig deep into our processes and mindset, you may also
17
want to peruse our extensive [first PR guide], which is part of our on-boarding for
18
new engineers.
19
23
24
- Either a working Docker install able to run GNU/Linux binaries
25
(e.g. Docker on Linux, macOS, Windows), so you can reuse our
26
pre-populated Docker image with all necessary development
27
dependencies; or
28
29
- The tools needed to build CockroachDB from scratch:
30
31
- A C++ compiler that supports C++11. Note that GCC prior to 6.0 doesn't
32
work due to https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48891
33
- The standard C/C++ development headers on your system.
34
- On GNU/Linux, the terminfo development libraries, which may be
35
part of a ncurses development package (e.g. `libtinfo-dev` on
36
Debian/Ubuntu, but `ncurses-devel` on CentOS).
37
- A Go environment with a recent 64-bit version of the toolchain. Note that
38
the Makefile enforces the specific version required, as it is updated
39
frequently.
40
- Git 1.9+
41
- Bash (4+ is preferred)
42
- GNU Make (3.81+ is known to work)
43
- CMake 3.1+
44
- Autoconf 2.68+
58
If you wish to reuse our builder image instead of installing all the
59
dependencies manually, prefix the `make` command with
60
`build/builder.sh`; for example `build/builder.sh make build`.
61
62
Note that the first time you run `make`, it can take some time to
63
download and install various dependencies. After running `make build`,
64
the `cockroach` executable will be in your current directory and can
65
be run as shown in the [README](README.md).
69
- The default binary contains core open-source functionally covered by
70
the Apache License 2 (APL2) and enterprise functionality covered by
71
the CockroachDB Community License (CCL). To build a pure open-source
72
(APL2) version excluding enterprise functionality, use `make
73
buildoss`. See this [blog post] for more details.
74
75
[blog post]: https://www.cockroachlabs.com/blog/how-were-building-a-business-to-last/
77
- If you edit a `.proto` or `.ts` file, you will need to manually
78
regenerate the associated `.pb.{go,cc,h}` or `.js` files using `make
79
generate`.
81
- You can also run `build/builder.sh make generate` from the
82
repository root to get the intended result.
86
- To add or update a Go dependency:
87
- See [`build/README.md`](build/README.md) for details on adding or updating
88
dependencies.
98
- All contributors need to sign the [Contributor License
99
Agreement](https://cla-assistant.io/cockroachdb/cockroach).
101
- Create a local feature branch to do work on, ideally on one thing at
102
a time. If you are working on your own fork, see [this
103
tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
104
on forking in Go, which ensures that Go import paths will be
105
correct.
110
125
# Run a specific sql logic subtest
126
make test PKG=./pkg/sql TESTS='TestLogic$$/select$$'
130
131
Logs are disabled during tests by default. To enable them, include
132
`TESTFLAGS="-v -show-logs"` as an argument the test command:
133
134
```shell
135
make test ... TESTFLAGS="-v -show-logs"
136
```
137
138
When you're ready to commit, be sure to write a Good Commit Message™. Consult
139
https://github.com/erlang/otp/wiki/Writing-good-commit-messages if you're
140
not sure what constitutes a Good Commit Message™.
141
In addition to the general rules referenced above, please also observe the
142
following guidelines:
143
- Prefix your commit subject line with the affected package, if one can easily
144
be chosen. For example, the subject line of a commit mostly affecting the
145
`server` package might read: "server: use net.Pipe instead of TCP HTTP/gRPC connections".
146
Commits which affect many packages as a result of a shared dependency change
147
should probably begin their subjects with the name of the shared dependency.
148
Finally, some commits may need to affect many packages in a way which does
149
not point to a specific package; those commits may begin with "*:" or "all:"
150
to indicate their reach.
151
- We publish detailed [release notes](https://www.cockroachlabs.com/docs/releases/)
152
describing most non-test changes. To facilitate this, at least one commit in every
153
PR (possibly the PR message/merge commit) should contain a brief description of
154
the change in terms that a user would recognize. This description should be prefixed
155
with "Release note:". For example, a commit like ["distsql: pre-reserve memory needed
156
to mark rows in HashJoiner build phase"](https://github.com/cockroachdb/cockroach/pull/18975)
157
might say "Release note: Fixed a panic in queries with `JOIN` using the
158
distributed SQL engine."
159
168
170
and contain a substantial (but not overwhelming) unit of work. You may also
171
want to `git fetch origin` and run
175
180
- Then [create a pull request using GitHub’s
181
UI](https://help.github.com/articles/creating-a-pull-request). If
182
you know of another GitHub user particularly suited to reviewing
183
your pull request, be sure to mention them in the pull request
184
body. If you possess the necessary GitHub privileges, please also
185
[assign them to the pull request using GitHub's
186
UI](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/).
189
- Address test failures and feedback by amending your commits. If your
190
change contains multiple commits, address each piece of feedback by
191
amending that commit to which the particular feedback is aimed. Wait
192
(or ask) for new feedback on those commits if they are not
193
straightforward. An `LGTM` ("looks good to me") by someone qualified
194
is usually posted when you're free to go ahead and merge. Most new
195
contributors aren't allowed to merge themselves; in that case, we'll
196
do it for you.
202
- the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
203
at `/debug/requests`. It has a breakdown of the recent traced
204
requests, in particularly slow ones. Two families are traced: `node`
205
and `coord`, the former (and likely more interesting one) containing
206
what happens inside of `Node`/`Store`/`Replica` and the other inside
207
of the coordinator (`TxnCoordSender`).
208
- [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
209
other things) heap and cpu profiles; [this golang blog
210
post](http://blog.golang.org/profiling-go-programs) explains it
211
extremely well and [this one by Dmitry
212
Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
219
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
220
```
221