Permalink
May 27, 2014
Sep 7, 2017
Sep 26, 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
Aug 18, 2016
May 27, 2014
Jul 31, 2016
May 27, 2014
Sep 26, 2017
Sep 26, 2017
Sep 26, 2017
Oct 28, 2015
Newer
100644
210 lines (164 sloc)
8.13 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.
19
20
- Either a working Docker install able to run GNU/Linux binaries
21
(e.g. Docker on Linux, macOS, Windows), so you can reuse our
22
pre-populated Docker image with all necessary development
23
dependencies; or
24
25
- The tools needed to build CockroachDB from scratch:
26
27
- A C++ compiler that supports C++11. Note that GCC prior to 6.0 doesn't
28
work due to https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48891
29
- The standard C/C++ development headers on your system.
30
- A Go environment with a recent 64-bit version of the toolchain. Note that
31
the Makefile enforces the specific version required, as it is updated
32
frequently.
33
- Git 1.9+
34
- Bash (4+ is preferred)
35
- GNU Make (3.81+ is known to work)
36
- CMake 3.1+
37
- Autoconf 2.68+
38
- Optional: NodeJS 6.x and Yarn 0.22.0+. Required when compiling protocol
39
buffers.
52
If you wish to reuse our builder image instead of installing all the
53
dependencies manually, prefix the `make` command with
54
`build/builder.sh`; for example `build/builder.sh make build`.
55
56
Note that the first time you run `make`, it can take some time to
57
download and install various dependencies. After running `make build`,
58
the `cockroach` executable will be in your current directory and can
59
be run as shown in the [README](README.md).
63
- The default binary contains core open-source functionally covered by
64
the Apache License 2 (APL2) and enterprise functionality covered by
65
the CockroachDB Community License (CCL). To build a pure open-source
66
(APL2) version excluding enterprise functionality, use `make
67
buildoss`. See this [blog post] for more details.
68
69
[blog post]: https://www.cockroachlabs.com/blog/how-were-building-a-business-to-last/
71
- If you edit a `.proto` or `.ts` file, you will need to manually
72
regenerate the associated `.pb.{go,cc,h}` or `.js` files using `make
73
generate`.
75
- You can also run `build/builder.sh make generate` from the
76
repository root to get the intended result.
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
- All contributors need to sign the [Contributor License
93
Agreement](https://cla-assistant.io/cockroachdb/cockroach).
95
- Create a local feature branch to do work on, ideally on one thing at
96
a time. If you are working on your own fork, see [this
97
tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
98
on forking in Go, which ensures that Go import paths will be
99
correct.
104
119
# Run a specific sql logic subtest
120
make test PKG=./pkg/sql TESTS='TestLogic$$/select$$'
124
125
Logs are disabled during tests by default. To enable them, include
126
`TESTFLAGS="-v -show-logs"` as an argument the test command:
127
128
```shell
129
make test ... TESTFLAGS="-v -show-logs"
130
```
131
132
When you're ready to commit, be sure to write a Good Commit Message™. Consult
133
https://github.com/erlang/otp/wiki/Writing-good-commit-messages if you're
134
not sure what constitutes a Good Commit Message™.
135
In addition to the general rules referenced above, please also prefix your
136
commit subject line with the affected package, if one can easily be chosen.
137
For example, the subject line of a commit mostly affecting the
138
`server/serverpb` package might read: "server/serverpb: made great again".
139
Commits which affect many packages as a result of a shared dependency change
140
should probably begin their subjects with the name of the shared dependency.
141
Finally, some commits may need to affect many packages in a way which does
142
not point to a specific package; those commits may begin with "*:" or "all:"
143
to indicate their reach.
152
154
and contain a substantial (but not overwhelming) unit of work. You may also
155
want to `git fetch origin` and run
159
164
- Then [create a pull request using GitHub’s
165
UI](https://help.github.com/articles/creating-a-pull-request). If
166
you know of another GitHub user particularly suited to reviewing
167
your pull request, be sure to mention them in the pull request
168
body. If you possess the necessary GitHub privileges, please also
169
[assign them to the pull request using GitHub's
170
UI](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/).
173
- Address test failures and feedback by amending your commits. If your
174
change contains multiple commits, address each piece of feedback by
175
amending that commit to which the particular feedback is aimed. Wait
176
(or ask) for new feedback on those commits if they are not
177
straightforward. An `LGTM` ("looks good to me") by someone qualified
178
is usually posted when you're free to go ahead and merge. Most new
179
contributors aren't allowed to merge themselves; in that case, we'll
180
do it for you.
186
- the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
187
at `/debug/requests`. It has a breakdown of the recent traced
188
requests, in particularly slow ones. Two families are traced: `node`
189
and `coord`, the former (and likely more interesting one) containing
190
what happens inside of `Node`/`Store`/`Replica` and the other inside
191
of the coordinator (`TxnCoordSender`).
192
- [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
193
other things) heap and cpu profiles; [this golang blog
194
post](http://blog.golang.org/profiling-go-programs) explains it
195
extremely well and [this one by Dmitry
196
Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
203
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
204
```
205