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
Nov 6, 2017
Dec 1, 2017
Nov 6, 2017
Dec 4, 2017
Nov 6, 2017
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
Sep 26, 2017
Oct 28, 2015
Newer
100644
251 lines (196 sloc)
9.82 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/
78
- If you edit a `.proto` or `.ts` file, you will need to manually
79
regenerate the associated `.pb.{go,cc,h}` or `.js` files using `make
80
generate`.
82
- You can also run `build/builder.sh make generate` from the
83
repository root to get the intended result.
87
- To add or update a Go dependency:
88
- See [`build/README.md`](build/README.md) for details on adding or updating
89
dependencies.
97
## Commit Messages
98
99
When you're ready to commit, be sure to write a Good Commit Message™. Consult
100
https://github.com/erlang/otp/wiki/Writing-good-commit-messages if you're
101
not sure what constitutes a Good Commit Message™.
102
In addition to the general rules referenced above, please also observe the
103
following guidelines:
104
105
- Prefix your commit subject line with the affected package, if one can easily
106
be chosen. For example, the subject line of a commit mostly affecting the
107
`server` package might read: "server: use net.Pipe instead of TCP HTTP/gRPC connections".
108
Commits which affect many packages as a result of a shared dependency change
109
should probably begin their subjects with the name of the shared dependency.
110
Finally, some commits may need to affect many packages in a way which does
111
not point to a specific package; those commits may begin with "\*:" or "all:"
112
to indicate their reach.
113
114
- We publish detailed [release notes](https://www.cockroachlabs.com/docs/releases/)
115
describing most non-test changes. To facilitate this, in every PR, at least one commit
116
should contain a brief description of the change in terms that a user would recognize.
117
Be sure to put these descriptions in commits and not in PR descriptions.
118
119
Each release note description should be prefixed with "Release note (category):",
120
where the "category" is one of the following:
124
- performance improvement
125
- bug fix
126
- general change (e.g., change of required Go version)
127
- build change (e.g., compatibility with older CPUs)
128
- enterprise change (e.g., change to backup/restore)
129
- backwards-incompatible change
130
131
This list is also documented in the commit message template, which lives in
132
githooks/prepare-commit-msg.
133
134
For example, a commit like ["distsql: pre-reserve memory needed
135
to mark rows in HashJoiner build phase"](https://github.com/cockroachdb/cockroach/pull/18975)
136
might say, "Release note (bug fix): Fixed a panic in queries with `JOIN` using the
137
distributed SQL engine."
138
139
When a commit falls into more than one category, choose the category that matches best
140
or is most affected from a user's perspective.
141
144
- All contributors need to sign the [Contributor License
145
Agreement](https://cla-assistant.io/cockroachdb/cockroach).
147
- Create a local feature branch to do work on, ideally on one thing at
148
a time. If you are working on your own fork, see [this
149
tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
150
on forking in Go, which ensures that Go import paths will be
151
correct.
156
171
# Run a specific sql logic subtest
172
make test PKG=./pkg/sql TESTS='TestLogic$$/select$$'
176
177
Logs are disabled during tests by default. To enable them, include
178
`TESTFLAGS="-v -show-logs"` as an argument the test command:
179
180
```shell
181
make test ... TESTFLAGS="-v -show-logs"
182
```
183
191
193
and contain a substantial (but not overwhelming) unit of work. You may also
194
want to `git fetch origin` and run
198
203
- Then [create a pull request using GitHub’s
204
UI](https://help.github.com/articles/creating-a-pull-request). If
205
you know of another GitHub user particularly suited to reviewing
206
your pull request, be sure to mention them in the pull request
207
body. If you possess the necessary GitHub privileges, please also
208
[assign them to the pull request using GitHub's
209
UI](https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/).
212
- Address test failures and feedback by amending your commits. If your
213
change contains multiple commits, address each piece of feedback by
214
amending that commit to which the particular feedback is aimed. Wait
215
(or ask) for new feedback on those commits if they are not
216
straightforward. An `LGTM` ("looks good to me") by someone qualified
217
is usually posted when you're free to go ahead and merge. Most new
218
contributors aren't allowed to merge themselves; in that case, we'll
219
do it for you.
225
- the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
226
at `/debug/requests`. It has a breakdown of the recent traced
227
requests, in particularly slow ones. Two families are traced: `node`
228
and `coord`, the former (and likely more interesting one) containing
229
what happens inside of `Node`/`Store`/`Replica` and the other inside
230
of the coordinator (`TxnCoordSender`).
231
- [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
232
other things) heap and cpu profiles; [this golang blog
233
post](http://blog.golang.org/profiling-go-programs) explains it
234
extremely well and [this one by Dmitry
235
Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
242
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
243
```
244