xref: /trunk/libcouchbase/CONTRIBUTING.md (revision d54c7953)
1e1f7f505SMark Nunberg# Contributing
272b94a95STrond Norbye
3b6e2238fSSergey AvseyevIn addition to filing bugs, you may contribute by submitting patches to fix bugs in the library. Contributions may be
4b6e2238fSSergey Avseyevsubmitting to <http://review.couchbase.com>.  We use Gerrit as our code review system - and thus submitting a change
54ede71ebSMatt Ingenthronrequires an account there. Note that pull requests will not be ignored
64ede71ebSMatt Ingenthronbut will be responded to more quickly and with more detail in Gerrit.
772b94a95STrond Norbye
8b6e2238fSSergey AvseyevFor something to be accepted into the codebase, it must be formatted properly and have undergone proper testing. While
9b6e2238fSSergey Avseyevthere are no formatting guidelines per se, the code should look similar to the existing code within the library.
1072b94a95STrond Norbye
11e1f7f505SMark Nunberg## Branches and Tags
1272b94a95STrond Norbye
13b6e2238fSSergey AvseyevReleased versions of the library are marked as annotated tags inside the repository.
1472b94a95STrond Norbye
15b6e2238fSSergey Avseyev* The `master` branch represents the mainline branch. The master branch typically consists of content going into the
16b6e2238fSSergey Avseyev  next release.
1772b94a95STrond Norbye
18e1f7f505SMark Nunberg## Contributing Patches
1972b94a95STrond Norbye
20b6e2238fSSergey AvseyevIf you wish to contribute a new feature or a bug fix to the library, try to follow the following guidelines to help
21b6e2238fSSergey Avseyevensure your change gets merged upstream.
2272b94a95STrond Norbye
23e1f7f505SMark Nunberg### Before you begin
2472b94a95STrond Norbye
25b6e2238fSSergey AvseyevFor any code change, ensure the new code you write looks similar to the code surrounding it. We have no strict code
26b6e2238fSSergey Avseyevstyle policies, but do request that your code stand out as little as possible from its surrounding neighborhood (unless
27e1f7f505SMark Nunbergof course your change is stylistic in nature).
2872b94a95STrond Norbye
29b6e2238fSSergey AvseyevIf your change is going to involve a substantial amount of time or effort, please attempt to discuss it with the project
30b6e2238fSSergey Avseyevdevelopers first who will provide assistance and direction where possible.
3172b94a95STrond Norbye
32b6e2238fSSergey AvseyevAdditionally, note that the library uses C89 (AKA "ANSI C") with some extensions that are known to work on both GCC and
33b6e2238fSSergey AvseyevVisual Studio for `.c` files, and C++11 for `.cc` files. Please ensure your code conforms to this, unless the new code
34b6e2238fSSergey Avseyevis specific to a given platform.
3572b94a95STrond Norbye
36e1f7f505SMark Nunberg#### For new features
37e1f7f505SMark Nunberg
38b6e2238fSSergey AvseyevEnsure the feature you are adding does not already exist, and think about how this feature may be useful for other
39b6e2238fSSergey Avseyevusers. In general less intrusive changes are more likely to be accepted.
40e1f7f505SMark Nunberg
41e1f7f505SMark Nunberg#### For fixing bugs
42e1f7f505SMark Nunberg
43b6e2238fSSergey AvseyevEnsure 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
44b6e2238fSSergey Avseyevversion. Please read the release notes as well as the issue tracker to see a list of open and resolved issues.
45e1f7f505SMark Nunberg
46e1f7f505SMark Nunberg### Code Review
47e1f7f505SMark Nunberg
48e1f7f505SMark Nunberg#### Signing up on Gerrit
49e1f7f505SMark Nunberg
50b6e2238fSSergey AvseyevEverything that is merged into the library goes through a code review process.  The code review process is done via
514ede71ebSMatt Ingenthron[Gerrit](http://review.couchbase.org).
52e1f7f505SMark Nunberg
53b6e2238fSSergey AvseyevTo sign up for a gerrit account, go to http://review.couchbase.org and click on the _Register_ link at the top
544ede71ebSMatt Ingenthronright. Once you've signed in you will need to agree to the CLA (Contributor License Agreement) by going you your gerrit
554ede71ebSMatt Ingenthronaccount page and selecting the _Agreements_ link on the left. When
564ede71ebSMatt Ingenthronyou've done that, everything should flow through just fine.  Be sure
574ede71ebSMatt Ingenthronthat you have registered your email address at
584ede71ebSMatt Ingenthronhttp://review.couchbase.org/#/settings/contact as many sign-up methods
594ede71ebSMatt Ingenthronwon't pass emails along.  Note that your email address in your code
604ede71ebSMatt Ingenthroncommit and in the gerrit settings must match.
61e1f7f505SMark Nunberg
624ede71ebSMatt IngenthronAdd your public SSH key to gerrit before submitting.
63e1f7f505SMark Nunberg
64e1f7f505SMark Nunberg#### Setting up your fork with Gerrit
65e1f7f505SMark Nunberg
66e1f7f505SMark NunbergAssuming you have a repository created like so:
67e1f7f505SMark Nunberg
68e1f7f505SMark Nunberg```
69*d54c7953SSergey Avseyev$ git clone https://github.com/couchbase/libcouchbase.git
70e1f7f505SMark Nunberg```
71e1f7f505SMark Nunberg
72e1f7f505SMark Nunbergyou can simply perform two simple steps to get started with gerrit:
73e1f7f505SMark Nunberg
74e1f7f505SMark Nunberg```
75e1f7f505SMark Nunberg$ git remote add gerrit ssh://${USERNAME}@review.couchbase.org:29418/libcouchbase
76e1f7f505SMark Nunberg$ scp -P 29418 ${USERNAME}@review.couchbase.org:hooks/commit-msg .git/hooks
77e1f7f505SMark Nunberg$ chmod a+x .git/hooks/commit-msg
78e1f7f505SMark Nunberg```
79e1f7f505SMark Nunberg
80b6e2238fSSergey AvseyevThe last change is required for annotating each commit message with a special header known as `Change-Id`. This allows
81b6e2238fSSergey AvseyevGerrit to group together different revisions of the same patch.
82e1f7f505SMark Nunberg
83e1f7f505SMark Nunberg#### Pushing a changeset
84e1f7f505SMark Nunberg
85b6e2238fSSergey AvseyevNow that you have your change and a gerrit account to push to, you need to upload the change for review. To do so,
86b6e2238fSSergey Avseyevinvoke the following incantation:
87e1f7f505SMark Nunberg
88e1f7f505SMark Nunberg```
89e1f7f505SMark Nunberg$ git push gerrit HEAD:refs/for/master
90e1f7f505SMark Nunberg```
91e1f7f505SMark Nunberg
92b6e2238fSSergey AvseyevWhere `gerrit` is the name of the _remote_ added earlier. You may encounter some errors when pushing. The most common
93e1f7f505SMark Nunbergare:
94e1f7f505SMark Nunberg
954ede71ebSMatt Ingenthron* "You are not authorized to push to this repository". You will get
964ede71ebSMatt Ingenthron  this if your account has not yet been approved.  Feel free to ask
974ede71ebSMatt Ingenthron  about in gitter.im/couchbase or in the forums for help if blocked.
98b6e2238fSSergey Avseyev* "Missing Change-Id". You need to install the `commit-msg` hook as described above.  Note that even once you do this,
99b6e2238fSSergey Avseyev  you will need to ensure that any prior commits already have this header - this may be done by doing an interactive
100b6e2238fSSergey Avseyev  rebase (e.g.  `git rebase -i origin/master` and selecting `reword` for all the commits; which will automatically fill
101b6e2238fSSergey Avseyev  in the Change-Id).
102e1f7f505SMark Nunberg
103b6e2238fSSergey Avseyev
104b6e2238fSSergey AvseyevOnce you've pushed your changeset you can add people to review. Currently these are:
105b6e2238fSSergey Avseyev
106b6e2238fSSergey Avseyev* Sergey Avseyev
107b6e2238fSSergey Avseyev* Brett Lawson
108b6e2238fSSergey Avseyev* Ellis Breen