Permalink
May 27, 2014
Sep 8, 2016
Feb 22, 2016
Jun 28, 2016
Aug 17, 2016
Jun 28, 2016
Jun 28, 2016
Jun 29, 2016
Jun 28, 2016
Jun 28, 2016
Jul 31, 2016
Jun 28, 2016
May 27, 2014
Jul 31, 2016
Oct 6, 2015
May 27, 2014
Aug 18, 2016
Aug 18, 2016
Jul 31, 2016
May 27, 2014
Jul 31, 2016
May 27, 2014
Aug 18, 2016
Jul 31, 2016
Aug 18, 2016
Jul 31, 2016
Oct 28, 2015
Jul 31, 2016
Jul 31, 2016
Oct 28, 2015
Oct 28, 2015
Jul 31, 2016
Newer
100644
163 lines (128 sloc)
7.09 KB
1
# Contributing to Cockroach
2
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.7.1
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. After running `make build`, the `cockroach` executable
23
will be in your current directory and can be run as shown in the
24
[README](README.md).
26
Note that if you edit a `.proto` or `.ts` file, you will need to manually
27
regenerate the associated `.pb.{go,cc,h}` or `.js` files using `go generate
28
./...`.
30
We advise to run `go generate` using our embedded Docker setup.
31
`build/builder.sh` is a wrapper script designed to make this convenient. You can
32
run `build/builder.sh env SKIP_BOOTSTRAP=0 go generate ./...` from the repository
33
root to get the intended result.
35
If you want to run it outside of Docker, `go generate` requires a collection of
36
Node.js modules which are installed via npm.
41
42
- `(cd $GOPATH/src && go get -u ./...)` to update the dependencies or `go get
43
`({package}` to add a dependency
44
- `glock save github.com/cockroachdb/cockroach` to update the GLOCKFILE
45
- `go generate ./...` to update generated files -- prefer
46
`go generate ./the-updated-package` instead of `...` when possible to avoid
56
+ All contributors need to sign the [Contributor License Agreement]
57
(https://cla-assistant.io/cockroachdb/cockroach).
65
66
+ Hack away and commit your changes locally using `git add` and `git commit`.
67
Remember to write tests! The following are helpful for running specific
71
make test
72
# Run all tests in ./storage
73
make test PKG=./storage
74
# Run all kv tests matching `^TestFoo` with a timeout of 10s
75
make test PKG=./kv TESTS='^TestFoo' TESTTIMEOUT=10s
76
```
77
78
When you're ready to commit, be sure to write a Good Commit Message™. Consult
79
https://github.com/erlang/otp/wiki/Writing-good-commit-messages if you're
80
not sure what constitutes a Good Commit Message™.
81
In addition to the general rules referenced above, please also prefix your
82
commit subject line with the affected package, if one can easily be chosen.
83
For example, the subject line of a commit mostly affecting the
84
`server/serverpb` package might read: "server/serverpb: made great again".
85
Commits which affect many packages as a result of a shared dependency change
86
should probably begin their subjects with the name of the shared dependency.
87
Finally, some commits may need to affect many packages in a way which does
88
not point to a specific package; those commits may begin with "*:" or "all:"
89
to indicate their reach.
91
+ Run the whole CI test suite locally: `./build/circle-local.sh`. This requires
92
the Docker setup; if you don't have/want that,
94
95
+ When you’re ready for review, groom your work: each commit should pass tests
96
and contain a substantial (but not overwhelming) unit of work. You may also
97
want to `git fetch origin` and run
98
`git rebase -i --exec "make check test" origin/master` to make sure you're
99
submitting your changes on top of the newest version of our code. Next, push
101
105
(https://help.github.com/articles/creating-a-pull-request). If you know of
106
another GitHub user particularly suited to reviewing your pull request, be
107
sure to mention them in the pull request body. If you possess the necessary
108
GitHub privileges, please also [assign them to the pull request using
109
GitHub's UI] (https://help.github.com/articles/assigning-issues-and-pull-requests-to-other-github-users/).
110
This will help focus and expedite the code review process.
112
+ If you get a test failure in CircleCI, check the Test Failure tab to see why
113
the test failed. When the failure is logged in `excerpt.txt`, you can find
114
the file from the Artifacts tab and see log messages. (You need to sign in to
117
+ Address feedback by amending your commits. If your change contains multiple
118
commits, address each piece of feedback by amending that commit to which the
119
particular feedback is aimed. Wait (or ask) for new feedback on those
120
commits if they are not straightforward. An `LGTM` ("looks good to me") by
121
someone qualified is usually posted when you're free to go ahead and merge.
122
Most new contributors aren't allowed to merge themselves; in that case, we'll
124
125
### Debugging
126
127
Peeking into a running cluster can be done in several ways:
128
129
* the [net/trace](https://godoc.org/golang.org/x/net/trace) endpoint at
130
`/debug/requests`. It has a breakdown of the recent traced requests, in
131
particularly slow ones. Two families are traced: `node` and `coord`, the
132
former (and likely more interesting one) containing what happens inside of
133
`Node`/`Store`/`Replica` and the other inside of the coordinator
139
(https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
140
goes into even more detail. Two caveats: the `cockroach` binary passed to
141
`pprof` must be the same as the one creating the profile (not true on OSX in
142
acceptance tests!), and the HTTP client used by `pprof` doesn't simply
143
swallow self-signed certs (relevant when using SSL). For the latter, a
145
146
```
147
go tool pprof cockroach <(curl -k https://$(hostname):26257/debug/pprof/profile)
148
```
154
155
```bash
156
make acceptance TESTS='TestPut$$' TESTFLAGS='-v -d 1200s -l .' TESTTIMEOUT=1210s
157
```
158
159
runs the `Put` acceptance test for 20 minutes with logging (useful to look at
160
the stacktrace in case of a node dying). When it starts, all the relevant
161
commands for `pprof`, `trace` and logs are logged to allow for convenient