1# Contributing
2
3In addition to filing bugs, you may contribute by submitting patches to fix bugs in the library. Contributions may be
4submitting to <http://review.couchbase.com>.  We use Gerrit as our code review system - and thus submitting a change
5would require an account there. Note that pull requests will not be ignored but will be responded to much quicker once
6they are converted into Gerrit.
7
8For something to be accepted into the codebase, it must be formatted properly and have undergone proper testing. While
9there are no formatting guidelines per se, the code should look similar to the existing code within the library.
10
11## Branches and Tags
12
13Released versions of the library are marked as annotated tags inside the repository.
14
15* The `master` branch represents the mainline branch. The master branch typically consists of content going into the
16  next release.
17
18## Contributing Patches
19
20If you wish to contribute a new feature or a bug fix to the library, try to follow the following guidelines to help
21ensure your change gets merged upstream.
22
23### Before you begin
24
25For any code change, ensure the new code you write looks similar to the code surrounding it. We have no strict code
26style policies, but do request that your code stand out as little as possible from its surrounding neighborhood (unless
27of course your change is stylistic in nature).
28
29If your change is going to involve a substantial amount of time or effort, please attempt to discuss it with the project
30developers first who will provide assistance and direction where possible.
31
32Additionally, note that the library uses C89 (AKA "ANSI C") with some extensions that are known to work on both GCC and
33Visual Studio for `.c` files, and C++11 for `.cc` files. Please ensure your code conforms to this, unless the new code
34is specific to a given platform.
35
36#### For new features
37
38Ensure the feature you are adding does not already exist, and think about how this feature may be useful for other
39users. In general less intrusive changes are more likely to be accepted.
40
41#### For fixing bugs
42
43Ensure the bug you are fixing is actually a bug (and not a usage) error, and that it has not been fixed in a more recent
44version. Please read the release notes as well as the issue tracker to see a list of open and resolved issues.
45
46### Code Review
47
48#### Signing up on Gerrit
49
50Everything that is merged into the library goes through a code review process.  The code review process is done via
51[Gerrit](http://review.couchbase.org) (Unfortunately we cannot merge pull requests, though it is fairly simple to
52convert a pull request to gerrit, as seen later. If you know a way to integrate pull requests with Gerrit, please let us
53know).
54
55To sign up for a gerrit account, go to http://review.couchbase.org and click on the _Register_ link at the top
56right. Once you've signed in you will need to sign the CLA (Contributor License Agreement) by going you your gerrit
57account page and selecting the _Agreements_ link on the left. When you've done that, be sure to notify us in IRC (at
58_#libcouchbase_) and/or send an email to **matt**AT**couchbase**DOTCOM as you will require manual approval before being
59able to submit a request for change.
60
61Once approved, you should add your public SSH key to gerrit.
62
63#### Setting up your fork with Gerrit
64
65Assuming you have a repository created like so:
66
67```
68$ git clone git://github.com/couchbase/libcouchbase.git
69```
70
71you can simply perform two simple steps to get started with gerrit:
72
73```
74$ git remote add gerrit ssh://${USERNAME}@review.couchbase.org:29418/libcouchbase
75$ scp -P 29418 ${USERNAME}@review.couchbase.org:hooks/commit-msg .git/hooks
76$ chmod a+x .git/hooks/commit-msg
77```
78
79The last change is required for annotating each commit message with a special header known as `Change-Id`. This allows
80Gerrit to group together different revisions of the same patch.
81
82#### Pushing a changeset
83
84Now that you have your change and a gerrit account to push to, you need to upload the change for review. To do so,
85invoke the following incantation:
86
87```
88$ git push gerrit HEAD:refs/for/master
89```
90
91Where `gerrit` is the name of the _remote_ added earlier. You may encounter some errors when pushing. The most common
92are:
93
94* "You are not authorized to push to this repository". You will get this if your account has not yet been approved.
95* "Missing Change-Id". You need to install the `commit-msg` hook as described above.  Note that even once you do this,
96  you will need to ensure that any prior commits already have this header - this may be done by doing an interactive
97  rebase (e.g.  `git rebase -i origin/master` and selecting `reword` for all the commits; which will automatically fill
98  in the Change-Id).
99
100
101Once you've pushed your changeset you can add people to review. Currently these are:
102
103* Sergey Avseyev
104* Brett Lawson
105* Ellis Breen
106