Skip to end of metadata
Go to start of metadata

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

For a very quick overview, watch the developing for couchbase introductory video.

Initial Account Setup

  • Login using your favorite OpenID provider.
  • Go to the gerrit 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.
  • 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) 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.

Initial Project Setup (for each project)

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

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

Just put the 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

Code Workflow

If you are using repo, please see the android docs to get started quickly.

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

Basically, do a normal topic branch 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).

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.

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.

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.

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.

  • 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.

Phase 3: Submit

Once the change is all verified, we can submit. We generally 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.

Links

For a good primer on Gerrit:

Gerrit Code Review at Wikibooks

Commit Tips and Style Hints

  • Read this information about good commit messages!
  • Read this blog post about good commit messages!
  • 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...
  • On style, don't have giant long lines, especially on your first summary line. More detailed information can be found
  • The best commits, too, are just like UNIX Philosophy.
    • The commit does one thing and does it well.
    • That is, a giant commit will probably be need to be broken up into smaller, bite-sized, easier to-digest commits.
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.