Changes (13)

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]&nbsp;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)). Make sure you get into the Northscale group for gerrit to work correctly. A correctly enabled account should see lots of activity.

* Go to the [gerrit settings|http://review.couchbase.org/#/settings/] and click on "Agreements" on the left hand side. Contributor agreements are needed for all projects except spymemcached. _Note to *new Couchbase employees*_: you should contact the helpdesk as your process is slightly different.

* While you wait for approval...

* To complete the setup...

** 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}manifest|https://github.com/couchbase/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]&nbsp;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").

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). By the way, don't see a reject as a bad thing. More eyes on a change will usually give it higher quality. It's less effort to fix things before they go in than after they're in a release.

* The best commit messages are like little blog posts. ** These can help to "sell" your commit to the community. * 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...