Permalink
May 27, 2014
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Feb 22, 2016
Mar 25, 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
205 lines (166 sloc)
7.52 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 ./...`.
31
32
We advise to run `go generate` using our embedded Docker
33
setup. `build/builder.sh` is a wrapper script designed to make this
34
convenient. You can run `build/builder.sh go generate ./...` from the
35
repository root to get the intended result.
36
37
If you want to run it outside of Docker, `go generate` requires a
38
collection of Node.js modules which are installed via npm.
39
40
If you plan on working on the UI, check out [the ui readme](ui).
43
- `(cd $GOPATH/src && go get -u ./...)` to update the dependencies or
44
`go get {package}` to add a dependency
45
- `glock save github.com/cockroachdb/cockroach` to update the
46
GLOCKFILE
47
- `go generate ./...` to update generated files -- prefer `go generate
48
./the-updated-package` instead of `...` when possible to avoid
49
re-generating files in directories where you haven't made any
50
changes.
54
55
We're following the
56
[Google Go Code Review](https://code.google.com/p/go-wiki/wiki/CodeReviewComments)
57
fairly closely. In particular, you want to watch out for proper
58
punctuation and capitalization in comments. We use two-space indents
59
in non-Go code (in Go, we follow `gofmt` which indents with
60
tabs). Format your code assuming it will be read in a window 100
64
When wrapping function signatures that do not fit on one line,
65
put the name, arguments, and return types on separate lines, with the closing `)`
66
at the same indentation as `func` (this helps visually separate the indented
67
arguments from the indented function body). Example:
68
```go
69
func (s *someType) myFunctionName(
70
arg1 somepackage.SomeArgType, arg2 int, arg3 somepackage.SomeOtherType,
71
) (somepackage.SomeReturnType, error) {
72
...
73
}
74
```
75
76
If the arguments list is too long to fit on a single line, switch to one
77
argument per line:
78
```go
79
func (s *someType) myFunctionName(
80
arg1 somepackage.SomeArgType,
81
arg2 int,
82
arg3 somepackage.SomeOtherType,
83
) (somepackage.SomeReturnType, error) {
84
...
85
}
86
```
87
88
If the return types need to be wrapped, use the same rules:
89
```go
90
func (s *someType) myFunctionName(
91
arg1 somepackage.SomeArgType, arg2 somepackage.SomeOtherType,
92
) (
93
somepackage.SomeReturnType,
94
somepackage.SomeOtherType,
95
error,
96
) {
97
...
98
}
99
```
100
108
[this tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
109
on forking in Go, which ensures that Go import paths will be correct.
112
113
+ Hack away and commit your changes locally using `git add` and `git
114
commit`. Remember to write tests! The following are helpful for
115
running specific subsets of tests:
116
117
```bash
118
make test
119
# Run all tests in ./storage
120
make test PKG=./storage
121
# Run all kv tests matching `^TestFoo` with a timeout of 10s
122
make test PKG=./kv TESTS='^TestFoo' TESTTIMEOUT=10s
123
```
124
125
When you're ready to commit, do just that with a succinct title and
126
informative message. For example,
127
128
```bash
129
$ git commit
130
> 'update CONTRIBUTING.md
131
>
132
> Added details on running specific tests via `make`, and
133
> the CircleCI-equivalent test suite.
134
>
135
> Fixed some formatting.'
136
```
138
+ Run the whole CI test suite locally: `./build/circle-local.sh`. This
139
requires the Docker setup; if you don't have/want that, `go generate
140
./... && make check test testrace` is a good first approximation.
141
142
+ When you’re ready for review, groom your work: each commit should
143
pass tests and contain a substantial (but not overwhelming) unit of
144
work. You may also want to `git fetch origin` and run `git rebase -i
145
--exec "make check test" origin/master` to make sure you're
146
submitting your changes on top of the newest version of our
147
code. Next, push to your fork:
148
151
+ Then
152
[create a pull request using GitHub’s UI](https://help.github.com/articles/creating-a-pull-request).
154
+ If you get a test failure in CircleCI, check the Test Failure tab to
155
see why the test failed. When the failure is logged in
156
`excerpt.txt`, you can find the file from the Artifacts tab and see
157
log messages. (You need to sign in to see the Artifacts tab.)
159
+ Address feedback in new commits. Wait (or ask) for new feedback on
160
those commits if they are not straightforward. An `LGTM` ("looks
161
good to me") by someone qualified is usually posted when you're free
162
to go ahead and merge. Most new contributors aren't allowed to merge
163
themselves; in that case, we'll do it for you. You may also be asked
164
to re-groom your commits.
166
167
### Debugging
168
169
Peeking into a running cluster can be done in several ways:
170
171
* the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
172
at `/debug/requests`. It has a breakdown of the recent traced
173
requests, in particularly slow ones. Two families are traced: `node`
174
and `coord`, the former (and likely more interesting one) containing
175
what happens inside of `Node`/`Store`/`Replica` and the other inside
176
of the coordinator (`TxnCoordSender`).
177
* [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
178
other things) heap and cpu profiles;
179
[this golang blog post](http://blog.golang.org/profiling-go-programs)
180
explains it extremely well and
181
[this one by Dmitry Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
182
goes into even more detail. Two caveats: the `cockroach` binary
183
passed to `pprof` must be the same as the one creating the profile
184
(not true on OSX in acceptance tests!), and the HTTP client used by
185
`pprof` doesn't simply swallow self-signed certs (relevant when
186
using SSL). For the latter, a workaround of the form
187
188
```
189
go tool pprof cockroach <(curl -k https://$(hostname):26257/debug/pprof/profile)
190
```
194
An easy way to locally run a workload against a cluster are the
195
acceptance tests. For example,
196
197
```bash
198
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
199
```
200