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