Permalink
May 27, 2014
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Oct 24, 2014
May 27, 2014
Feb 22, 2016
Oct 6, 2015
May 27, 2014
Feb 22, 2016
May 27, 2014
Oct 6, 2015
Feb 22, 2016
May 27, 2014
Feb 22, 2016
May 27, 2014
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Oct 28, 2015
Feb 22, 2016
Oct 28, 2015
Feb 22, 2016
Oct 28, 2015
Newer
100644
160 lines (127 sloc)
6.33 KB
1
# Contributing to Cockroach
2
6
- A C++ compiler that supports C++11 (GCC 4.9+ and clang 3.6+ are
7
known to work). On Mac OS X, Xcode should suffice.
8
- A [Go environment](http://golang.org/doc/code.html) with a
9
64-bit version of Go 1.6. You can download the
10
[Go binary](https://golang.org/dl/) directly from the official
11
site. On OS X, you can also use [homebrew](http://brew.sh):
12
`brew install go`. Be sure to set the `$GOPATH` and `$PATH`
13
environment variables as described
14
[here](https://golang.org/doc/code.html#GOPATH).
15
- Git 1.8+
19
```bash
20
go get -d github.com/cockroachdb/cockroach
21
cd $GOPATH/src/github.com/cockroachdb/cockroach
22
```
24
3. Run `make build`, `make test`, or anything else our Makefile
25
offers. Note that the first time you run `make`, it can take some
26
time to download and install various dependencies.
28
Note that if you edit a `.proto` or `.ts` file, you will need to
29
manually regenerate the associated `.pb.{go,cc,h}` or `.js` files
30
using `go generate ./...`. `go generate` requires a collection of
31
node modules which are installed via npm. If you don't have npm, it
32
typically comes with node. To get it via homebrew: `brew install node`
33
If you're not using homebrew, make sure you install both
34
[node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/). If
35
you plan on working on the UI, check out [the ui readme](ui).
38
- `(cd $GOPATH/src && go get -u ./...)` to update the dependencies or
39
`go get {package}` to add a dependency
40
- `glock save github.com/cockroachdb/cockroach` to update the
41
GLOCKFILE
46
47
We're following the
48
[Google Go Code Review](https://code.google.com/p/go-wiki/wiki/CodeReviewComments)
49
fairly closely. In particular, you want to watch out for proper
50
punctuation and capitalization in comments. We use two-space indents
51
in non-Go code (in Go, we follow `gofmt` which indents with
52
tabs). Format your code assuming it will be read in a window 100
53
columns wide. Wrap code and comments at 100 characters unless doing so
54
makes the code less legible.
63
[this tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
64
on forking in Go, which ensures that Go import paths will be correct.
67
68
+ Hack away and commit your changes locally using `git add` and `git
69
commit`. Remember to write tests! The following are helpful for
70
running specific subsets of tests:
71
72
```bash
73
make test
74
# Run all tests in ./storage
75
make test PKG=./storage
76
# Run all kv tests matching `^TestFoo` with a timeout of 10s
77
make test PKG=./kv TESTS='^TestFoo' TESTTIMEOUT=10s
78
```
79
80
When you're ready to commit, do just that with a succinct title and
81
informative message. For example,
82
83
```bash
84
$ git commit
85
> 'update CONTRIBUTING.md
86
>
87
> Added details on running specific tests via `make`, and
88
> the CircleCI-equivalent test suite.
89
>
90
> Fixed some formatting.'
91
```
93
+ Run the whole CI test suite locally: `./build/circle-local.sh`. This
94
requires the Docker setup; if you don't have/want that, `go generate
95
./... && make check test testrace` is a good first approximation.
96
97
+ When you’re ready for review, groom your work: each commit should
98
pass tests and contain a substantial (but not overwhelming) unit of
99
work. You may also want to `git fetch origin` and run `git rebase -i
100
--exec "make check test" origin/master` to make sure you're
101
submitting your changes on top of the newest version of our
102
code. Next, push to your fork:
103
106
+ Then
107
[create a pull request using GitHub’s UI](https://help.github.com/articles/creating-a-pull-request).
109
+ If you get a test failure in CircleCI, check the Test Failure tab to
110
see why the test failed. When the failure is logged in
111
`excerpt.txt`, you can find the file from the Artifacts tab and see
112
log messages. (You need to sign in to see the Artifacts tab.)
114
+ Address feedback in new commits. Wait (or ask) for new feedback on
115
those commits if they are not straightforward. An `LGTM` ("looks
116
good to me") by someone qualified is usually posted when you're free
117
to go ahead and merge. Most new contributors aren't allowed to merge
118
themselves; in that case, we'll do it for you. You may also be asked
119
to re-groom your commits.
121
122
### Debugging
123
124
Peeking into a running cluster can be done in several ways:
125
126
* the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
127
at `/debug/requests`. It has a breakdown of the recent traced
128
requests, in particularly slow ones. Two families are traced: `node`
129
and `coord`, the former (and likely more interesting one) containing
130
what happens inside of `Node`/`Store`/`Replica` and the other inside
131
of the coordinator (`TxnCoordSender`).
132
* [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
133
other things) heap and cpu profiles;
134
[this golang blog post](http://blog.golang.org/profiling-go-programs)
135
explains it extremely well and
136
[this one by Dmitry Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
137
goes into even more detail. Two caveats: the `cockroach` binary
138
passed to `pprof` must be the same as the one creating the profile
139
(not true on OSX in acceptance tests!), and the HTTP client used by
140
`pprof` doesn't simply swallow self-signed certs (relevant when
141
using SSL). For the latter, a workaround of the form
142
143
```
144
go tool pprof cockroach <(curl -k https://$(hostname):26257/debug/pprof/profile)
145
```
149
An easy way to locally run a workload against a cluster are the
150
acceptance tests. For example,
151
152
```bash
153
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
154
```
155