1# Contributing
2
3We've decided to use Gerrit for our code review system, making it
4easier for all of us to contribute with code and comments.
5
6There are some prerequisites before you can start contributing, so be sure to start with the following:
7
8  1. Visit [http://review.couchbase.org](http://review.couchbase.org) and "Register" for an account
9  2. Review [our Contributor Licence Agreement (CLA)](http://review.couchbase.org/static/individual_agreement.html)
10  3. Agree to CLA by visiting [http://review.couchbase.org/#/settings/agreements](http://review.couchbase.org/#/settings/agreements)
11     Otherwise, you won't be able to push changes to Gerrit (instead getting a "`Upload denied for project`" message).
12  4. If you do not receive an email, please contact us
13  5. Have a look at current changes in review in the java client area [http://review.couchbase.org/#/q/status:open+project:couchbase-java-client,n,z](http://review.couchbase.org/#/q/status:open+project:couchbase-java-client,n,z)
14  6. Join us on IRC at #libcouchbase on Freenode :-)
15
16General information on contributing to Couchbase projects can be found on the [website](http://developer.couchbase.com/open-source-projects#how-to-contribute-code) and in the [wiki](http://www.couchbase.com/wiki/display/couchbase/Contributing+Changes).
17
18## Building and Testing Locally
19Note that to build `SNAPSHOT` versions of the `java-client` you also need to build the `core-io` package on which it depends.
20Both use maven to package and install. The same process as above applies for the [core-io](https://github.com/couchbase/couchbase-jvm-core) package.
21
22After you've checked out both projects (from github) you can build and install them as follows:
23
24```
25┌─[michael@daschlbase]─[~/code/couchbase/couchbase-jvm-core]
26└──╼ mvn clean install
27**SNIP**
28[INFO] --- maven-install-plugin:2.4:install (default-install) @ core-io ---
29[INFO] Installing /Users/michaelnitschinger/code/couchbase/couchbase-jvm-core/target/core-io-1.2.1-SNAPSHOT.jar to /Users/michaelnitschinger/.m2/repository/com/couchbase/client/core-io/1.2.1-SNAPSHOT/core-io-1.2.1-SNAPSHOT.jar
30[INFO] Installing /Users/michaelnitschinger/code/couchbase/couchbase-jvm-core/dependency-reduced-pom.xml to /Users/michaelnitschinger/.m2/repository/com/couchbase/client/core-io/1.2.1-SNAPSHOT/core-io-1.2.1-SNAPSHOT.pom
31[INFO] Installing /Users/michaelnitschinger/code/couchbase/couchbase-jvm-core/target/core-io-1.2.1-SNAPSHOT-sources.jar to /Users/michaelnitschinger/.m2/repository/com/couchbase/client/core-io/1.2.1-SNAPSHOT/core-io-1.2.1-SNAPSHOT-sources.jar
32[INFO] Installing /Users/michaelnitschinger/code/couchbase/couchbase-jvm-core/target/core-io-1.2.1-SNAPSHOT-javadoc.jar to /Users/michaelnitschinger/.m2/repository/com/couchbase/client/core-io/1.2.1-SNAPSHOT/core-io-1.2.1-SNAPSHOT-javadoc.jar
33[INFO] Installing /Users/michaelnitschinger/code/couchbase/couchbase-jvm-core/target/core-io-1.2.1-SNAPSHOT-sources.jar to /Users/michaelnitschinger/.m2/repository/com/couchbase/client/core-io/1.2.1-SNAPSHOT/core-io-1.2.1-SNAPSHOT-sources.jar
34[INFO] ------------------------------------------------------------------------
35[INFO] BUILD SUCCESS
36[INFO] ------------------------------------------------------------------------
37[INFO] Total time: 52.676 s
38[INFO] Finished at: 2015-10-12T07:18:50+02:00
39[INFO] Final Memory: 36M/337M
40[INFO] ------------------------------------------------------------------------
41```
42
43Next, the exact steps apply for the  `java-client`.
44
45Note that installing includes running the tests, which require you to run a local Couchbase Server 4.0 or later instance.
46If you want to avoid building the tests over and over again, you can add the `-Dmaven.test.skip` flag to the command line.
47If you only want to run the unit tests (also no server required for them), use the `-Dunit` flag (recommended over skipping the tests entirely).
48
49## Preparing for Contribution
50Gerrit needs a little bit of setup in the repository of the project you are planning to contribute to.
51
52> **Tip**: [Here](https://www.mediawiki.org/wiki/Gerrit/Tutorial) is an extensive tutorial on how to work with git and
53Gerrit. It includes explanations about a [`git-review`](https://github.com/openstack-infra/git-review) CLI tool that can
54be used to work with Gerrit instead of the bare git commands described in the following sections.
55
56You should already have created a Gerrit account and associated it with a SSH key, as well as having signed the Contributor Licence Agreement (CLA, see introduction).
57
58You should also have performed a `git clone` of the project from Github, so we'll assume you're in the project's directory, `couchbase-java-client/`.
59
60First you need to add a remote for Gerrit (replace `YOUR_SSH_USERNAME` with the relevant value from your ssh config):
61
62```bash
63git remote add gerrit ssh://YOUR_SSH_USERNAME@review.couchbase.org:29418/couchbase-java-client.git
64```
65
66You'll also need to install a commit hook script that will generate a new Gerrit Change-Id each time you make a brand new commit:
67
68```bash
69cd .git/hooks
70wget http://review.couchbase.com/tools/hooks/commit-msg
71chmod +x commit-msg
72```
73
74Keep in mind that in Gerrit (unlike Github's Pull Requests), all iterations of a particular change **must** take place in a single commit.
75This is done by using `git commit --amend` (or rebasing and squashing) each time you make alterations to your change.
76The discussion takes place inside of Gerrit's UI (it will provide you the URL to the change when pushing), and the history
77of the change is internally maintained by Gerrit so you can actually compare each revision despite having used --amend.
78
79## Making the Change
80The previous step is a one-time configuration of the repository. The following must be done for each new contribution.
81
82Before you start coding, you should usually open an issue in the [Couchbase bug tracker](https://issues.couchbase.com/projects/JCBC/)
83(JIRA), under the relevant project: `JCBC` for Couchbase Java Client (java-client) and `JVMCBC` for Java Couchbase JVM
84Core (core-io). That may avoid unnecessary effort, for example if the change you are planning to make is going to be
85obsolete because of a modification we've already planned.
86
87This will also give the change an issue number that you can reference in the commit.
88
89To prepare a patch for the `master` branch, start from it and preferably create a new branch for your patch:
90
91```bash
92# this will be kept local, so you can use a very simple branch name
93git checkout master -b myPatch
94# or a fancier branch name :-)
95git checkout master -b contribs/JCBC-XXX-myPatch
96```
97
98Make your changes and do the first commit, it will be issued a Change-Id:
99
100```
101git commit
102```
103
104Your preferred text editor should open for you to fill in the commit message. Note that we use a template for commit
105messages that looks like this:
106
107```txt
108##IDEAL SIZE FOR COMMIT TITLE (50char)###########
109#<TICKET-NR>: Commit Short Info, goes in Changelog
110
111#Motivation
112#----------
113## UNCOMMENT THE ABOVE IF THE SECTION IS RELEVANT
114
115##IDEAL SIZE FOR BODY (72char)#########################################
116# A few lines about why this change is needed at all. Probably a bug
117# that has shown up or why the enhancement, or new feature makes sense.
118
119#Modifications
120#-------------
121## UNCOMMENT THE ABOVE IF THE SECTION IS RELEVANT
122
123##IDEAL SIZE FOR BODY (72char)#########################################
124# Explicit info about what has changed, more comments on the code that
125# has changed and explicitly state breaking changes or things that
126# impact users.
127
128#Result
129#------
130## UNCOMMENT THE ABOVE IF THE SECTION IS RELEVANT
131
132##IDEAL SIZE FOR BODY (72char)#########################################
133# What’s the outcome of the change? For example if there is a
134# performance optimization adding before/after numbers here make sense.
135```
136
137>**`TICKET-NR`** is the Jira issue id you have created, eg. `JCBC-123`.
138>
139> If you want to verify that the Change-Id was correctly generated, look at the end of the commit message in `git log`,
140> it should appear there.
141
142Example of a very short commit message that follows this template:
143
144```txt
145JCBC-123: Fix MadeUpClass array out of bounds
146
147Motivation
148----------
149The MadeUpClass uses an array of 128 ints internally, but sometimes we
150query it with an index of 256...
151
152Modifications
153-------------
154Use Math.min to limit the index we query with.
155
156Added a unit test to avoid regressions on this bug in the future.
157
158Result
159------
160No more ArrayIndexOutOfBoundsException. This bug is now tested against.
161```
162
163> Notice the IDEAL SIZE lines in the template have the recommended maximum length for the section.
164>
165> Notice as well that in the above we uncommented the section headers and filled something in for each section.
166
167If you want to add modifications or you come back to the change later (eg. because of discussions in Gerrit), **don't
168forget to use `--amend`** (and don't modify the last lines where Gerrit metadata are appended, especially the Change-Id):
169
170```bash
171# to also edit the commit message:
172git commit --amend
173# if the commit message is already good:
174git commit --amend --no-edit
175```
176
177Finally, to upload the change to Gerrit (as a new Changeset) or a later modification (as a new Patchset inside the
178Changeset), push to the Gerrit remote's special branch:
179
180```bash
181git push gerrit HEAD:refs/for/master
182```
183
184> **Note:** As stated earlier there is a CLI tool, [`git-review`](https://github.com/openstack-infra/git-review)
185> from OpenStack for dealing with Gerrit-specific commands. The above would be replaced by `git review -R`.
186>
187> And it generates the Change-Id, so no need to set up the commit hook manually.
188
189Gerrit should answer with the URL to your Changeset, where you can call for reviewers (for the Java SDK, `Michael Nitschinger`).
190
191To mark a changeset as ready for review (you are confident the change is complete with code and tests, and you have
192executed all unit tests and preferably all integration tests), you can use the "Reply..." button, top right and give
193"`Verified`" a note of +1.
194
195Reviewers will be notified and will look at your change, replying with a "`Code-Review`" mark between -2 and +2.
196If <= 0, there should be comments visible in the bottom list, starting a discussion to improve the change until a later
197patchset can receive a `Code-Review +2` and be merged in.
198
199## Troubleshooting
200### "Upload denied for project"
201If you get the following error while attempting to push your first change to Gerrit:
202```
203fatal: Upload denied for project 'couchbase-java-client'
204fatal: Could not read from remote repository.
205Please make sure you have the correct access rights
206and the repository exists.
207```
208
209Make sure that you have accepted the CLA as described in step 3. of the intro. Also please check your ssh configuration.
210
211This applies both when using bare git (`git push gerrit HEAD:refs/for/master`) or git-review ( `git review -R`).
212
213## Final Note
214Finally, feel free to reach out to the maintainers over the forums, IRC or email ([sdk_dev@couchbase.com](mailto:sdk_dev@couchbase.com))
215if you have further questions on contributing or get stuck along the way. **We love contributions and want to help you
216get your change over the finish line - and you mentioned in the release notes!**
217