Permalink
May 27, 2014
Jun 27, 2016
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
155 lines (119 sloc)
5.81 KB
1
# Contributing to Cockroach
2
6
- A C++ compiler that supports C++11. Note that GCC prior to 6.0 doesn't
7
work due to https://gcc.gnu.org/bugzilla/show_bug.cgi?id=48891
8
- A Go environment with a 64-bit version of Go 1.6.2.
9
- Git 1.8+.
13
```bash
14
go get -d github.com/cockroachdb/cockroach
15
cd $GOPATH/src/github.com/cockroachdb/cockroach
16
```
18
3. Run `make build`, `make test`, or anything else our Makefile
19
offers. Note that the first time you run `make`, it can take some
20
time to download and install various dependencies.
22
Note that if you edit a `.proto` or `.ts` file, you will need to
23
manually regenerate the associated `.pb.{go,cc,h}` or `.js` files
24
using `go generate ./...`.
25
26
We advise to run `go generate` using our embedded Docker
27
setup. `build/builder.sh` is a wrapper script designed to make this
28
convenient. You can run `build/builder.sh go generate ./...` from the
29
repository root to get the intended result.
30
31
If you want to run it outside of Docker, `go generate` requires a
32
collection of Node.js modules which are installed via npm.
33
34
If you plan on working on the UI, check out [the ui readme](ui).
37
- `(cd $GOPATH/src && go get -u ./...)` to update the dependencies or
38
`go get {package}` to add a dependency
39
- `glock save github.com/cockroachdb/cockroach` to update the
40
GLOCKFILE
41
- `go generate ./...` to update generated files -- prefer `go generate
42
./the-updated-package` instead of `...` when possible to avoid
43
re-generating files in directories where you haven't made any
44
changes.
58
[this tip](http://blog.campoy.cat/2014/03/github-and-go-forking-pull-requests-and.html)
59
on forking in Go, which ensures that Go import paths will be correct.
62
63
+ Hack away and commit your changes locally using `git add` and `git
64
commit`. Remember to write tests! The following are helpful for
65
running specific subsets of tests:
66
67
```bash
68
make test
69
# Run all tests in ./storage
70
make test PKG=./storage
71
# Run all kv tests matching `^TestFoo` with a timeout of 10s
72
make test PKG=./kv TESTS='^TestFoo' TESTTIMEOUT=10s
73
```
74
75
When you're ready to commit, do just that with a succinct title and
76
informative message. For example,
77
78
```bash
79
$ git commit
80
> 'update CONTRIBUTING.md
81
>
82
> Added details on running specific tests via `make`, and
83
> the CircleCI-equivalent test suite.
84
>
85
> Fixed some formatting.'
86
```
88
+ Run the whole CI test suite locally: `./build/circle-local.sh`. This
89
requires the Docker setup; if you don't have/want that, `go generate
90
./... && make check test testrace` is a good first approximation.
91
92
+ When you’re ready for review, groom your work: each commit should
93
pass tests and contain a substantial (but not overwhelming) unit of
94
work. You may also want to `git fetch origin` and run `git rebase -i
95
--exec "make check test" origin/master` to make sure you're
96
submitting your changes on top of the newest version of our
97
code. Next, push to your fork:
98
101
+ Then
102
[create a pull request using GitHub’s UI](https://help.github.com/articles/creating-a-pull-request).
104
+ If you get a test failure in CircleCI, check the Test Failure tab to
105
see why the test failed. When the failure is logged in
106
`excerpt.txt`, you can find the file from the Artifacts tab and see
107
log messages. (You need to sign in to see the Artifacts tab.)
109
+ Address feedback in new commits. Wait (or ask) for new feedback on
110
those commits if they are not straightforward. An `LGTM` ("looks
111
good to me") by someone qualified is usually posted when you're free
112
to go ahead and merge. Most new contributors aren't allowed to merge
113
themselves; in that case, we'll do it for you. You may also be asked
114
to re-groom your commits.
116
117
### Debugging
118
119
Peeking into a running cluster can be done in several ways:
120
121
* the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint
122
at `/debug/requests`. It has a breakdown of the recent traced
123
requests, in particularly slow ones. Two families are traced: `node`
124
and `coord`, the former (and likely more interesting one) containing
125
what happens inside of `Node`/`Store`/`Replica` and the other inside
126
of the coordinator (`TxnCoordSender`).
127
* [pprof](https://golang.org/pkg/net/http/pprof/) gives us (among
128
other things) heap and cpu profiles;
129
[this golang blog post](http://blog.golang.org/profiling-go-programs)
130
explains it extremely well and
131
[this one by Dmitry Vuykov](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
132
goes into even more detail. Two caveats: the `cockroach` binary
133
passed to `pprof` must be the same as the one creating the profile
134
(not true on OSX in acceptance tests!), and the HTTP client used by
135
`pprof` doesn't simply swallow self-signed certs (relevant when
136
using SSL). For the latter, a workaround of the form
137
138
```
139
go tool pprof cockroach <(curl -k https://$(hostname):26257/debug/pprof/profile)
140
```
144
An easy way to locally run a workload against a cluster are the
145
acceptance tests. For example,
146
147
```bash
148
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
149
```
150