Contributing Changes

{panel:bgColor=#f0f0f0}
{toc:outline=true|style=none|indent=10px}
{panel}

This page describes how we use the Gerrit code review system along with Git.

For a very quick overview, watch the [developing for couchbase|http://downloads.northscale.com/video/developing-couchbase.m4v] introductory video.

h1. Initial Account Setup

* [http://review.couchbase.org/]

* Login using your favorite OpenID provider.

* Send [me|mailto:dustin@couchbase.com,matt@couchbase.com?subject=Hey,%20I'm%20a%20gerrit%20user] the email address you came in with so he can add you to the right gerrit group (otherwise you'll see only a couple or fewer fixes for review (these are likely open-source fixes)). A correctly enabled account should see lots of activity.

* While you wait for approval...
** Go through gerrit's Settings screen and set up your SSH keys. IMPORTANT: - do not forget to setup your username on the Settings screen.
** Again, the username setup in gerrit \-> Settings \-> SSH Keys ([http://review.couchbase.org/#settings,ssh-keys|http://review.couchbase.org/#settings,ssh-keys]) is important. Folks have been bitten for not doing the username setup while setting up SSH keys.

* And setup your contact information if you'd rather use a different Email address.

h1. Initial Project Setup (for each project)

{note}This is not necessary if you intend to use repo. For a repo with membase quick start, please see the README in our [repo manifest|https://github.com/membase/manifest]{note}

Next, you'll need Change-Id's in all of your commit messages.

Just put the [commit-msg|http://review.couchbase.org/tools/hooks/commit-msg] script in .git/hooks of the repository you are working with and make sure it's executable. For example, you should have...

{{$MY_REPOSITORY/.git/hooks/commit-msg}}

You can test that you've setup the commit-msg script correctly by doing a commit and then looking at the log. You should see a "Change-Id: I\[hex\]" line show up in your commit message text.

Add a gerrit remote in each project (or just clone the gerrit git URL and use "origin" instead of "gerrit").

{{git remote add gerrit ssh://review.couchbase.org:29418/(PROJECT_NAME).git}}

For example, if the project you're working on is ns_server, do...

{{git remote add gerrit ssh://review.couchbase.org:29418/ns_server.git}}

h1. Code Workflow

{note}If you are using repo, please see the [android docs|http://source.android.com/source/git-repo.html] to get started quickly.{note}

Next, let's describe how you get your code up for review...

Basically, do a normal [topic branch|http://progit.org/book/ch3-4.html] workflow.

* First, make sure you have a remote set up for gerrit
** {{git remote add gerrit ssh://review.couchbase.org:29418/\[PROJECT_NAME\].git}}
*** For example: {{git remote add gerrit ssh://review.couchbase.org:29418/ns_server.git}}
** {{git fetch gerrit}}
* Create a branch.
** {{git branch bug_666 gerrit/\[BRANCH_NAME\]}}
*** For example: {{git branch bug_666 gerrit/master}}
** {{git checkout bug_666}}
* Make all of the topic-specific changes on you branch.
* {{git push gerrit HEAD:refs/for/\[BRANCH_NAME\]}}
** For example: {{git push gerrit HEAD:refs/for/master}}

You should next go into the gerrit's web page for the change's and add reviewers. Otherwise, it's unlikely anyone will review your code. Adding a reviewer causes the change to show up in the reviewer's "Reviewable by me" list, and they also get an email.

Others will go and review your code (you can also request reviews specifically in the admin UI).

h1. Review Workflow

It's good to learn the key combinations (hit ? anywhere), but in general, you can see all of the open changes by going to All \-> Open and digging through them.

h3. Phase 1: Reviewable

Dig around, look at things to review, and throw in your comments. You can comment on individual code lines.

Also, with regards to dependencies, if the fix you're reviewing depends on another fix, review the dependency first. That is, follow the dependency link trail until you hit a fix that has no dependencies. This helps ensure the right cherry-pick sequencing (gerrit does cherry-picking automatically for us if we do it right).

It takes two points for code to be acceptable. Everyone has two points to spend on a given change. Use them wisely.

h2. Phase 2: Needs verification

You can do this at the same time as the review, but you have the ability to pull down the changes to test locally.

h2. Phase 2.5: Rejected\!

If your code was rejected, it's time for a fix and retry: Fix, rebase, repeat (the Change-Id will keep old comments in sync).

* {{git checkout my-rejected-topic-branch}}
* {{$EDITOR broken-file.erl}}
* \# Rebase against the current upstream, fixup changes while maintaining Change-Id
* {{git rebase \-i gerrit/\[BRANCH_NAME\]}}
** For example: {{git rebase \-i gerrit/master}}
* {{git push gerrit HEAD:refs/for/\[BRANCH_NAME\]}}
** For example: {{git push gerrit HEAD:refs/for/master}}

The rebase session will begin with you in an editor that looks something like the one to the right:

At this point, your current patch should be replaced with the new, fixed up version.

h2. Phase 3: Submit

Once the change is all verified, we can submit. We use cherry-pick, which means we need to be a bit careful to do this in order.

Once the submit is complete, the change will automatically show up on github, as we publish changes there too.

h1. Links

For a good primer on Gerrit:

[Gerrit Code Review at Wikibooks|http://en.wikibooks.org/wiki/Git/Gerrit_Code_Review#Submitting_changes_for_review]

* Here's examples where the commit message was much longer than the actual fix, but provided useful context as those one-liner fixes can sometimes be very intricate...

** That is, a giant commit will probably be need to be broken up into smaller, bite-sized, easier to-digest commits.