Contributing to Mylyn through Gerrit Code Reviews

by Steffen Pingel, October 24th, 2011

If the length of the CC list is any indication of interest in a bug, a lot of committers are looking forward to Gerrit support at Eclipse.org. The webmasters are working hard on making that happen but for Mylyn we were so eager to integrate code reviews in our workflow that we went ahead and deployed a Gerrit instance outside of Eclipse.org. Although the server has only been running for a few weeks, over 50 reviews have already been opened by a dozen people. Read on for a description how to setup your workspace to start contributing to Mylyn.

The server setup with Gerrit 2.2.1 and Hudson 2.1.2 follows the configuration described in Alex Blewitt’s tutorial. Every time an update to a Gerrit change is pushed, a Hudson build is triggered, and the result is reported back on the code review. After having worked that way for a while I would not want to miss the benefits of quick validation of staged commits and the simplified feedback process for contributions and changes proposed by committers.

Registering a Gerrit Account

To use the review server a few steps are required:

  1. Register an account at review.mylyn.org using an Open ID provider such as Google
  2. Define a username
  3. Upload your public ssh-key for authentication

Once the account has been created you need to contact me to get the account added to the trusted users group which has the required permissions to create code reviews.

Adding Gerrit as a Git Remote

On the client end, Gerrit is simply added as another remote to the local clone of a Mylyn Git repository. For example, the .git/config file for the Mylyn Tasks git repository would specify these two remotes:

[remote "origin"]
  fetch = +refs/heads/*:refs/remotes/origin/*
  url = git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.tasks.git
  push = HEAD:refs/heads/master

[remote "gerrit"]
  url = ssh://spingel@review.mylyn.org:29418/org.eclipse.mylyn.tasks.git
  fetch = +refs/heads/master:refs/remotes/gerrit/master
  push = HEAD:refs/for/master

If you have cloned any of the Mylyn repositories already, you can simply add the gerrit remote section. No need to clone again. Note that Gerrit uses a special ref for the push configuration called refs/for/master. This ensures that changes are not directly pushed into the master but staged in a branch first.

Additionally, I recommend adding these settings to the .git/config file:

[gerrit]
  createchangeid = true

[branch]
  autosetuprebase = always

The createchangeid flag causes EGit to automatically generate a Change-Id header for each commit. This id is used by Gerrit to track updates to existing code reviews. The autosetuprebase flag will cause all new remote tracking branches to be configured for rebase automatically which is useful when updating task branches.

Creating a Code Review

To push a new code review to review.mylyn.org, first create a local branch to track your change. This is good practice and makes it easy to modify the change based on feedback from the code review later.

$ git checkout -t origin/master -b bug#191522-provide-full-text-search

Now go ahead and commit to the branch.

The next step is to create the code review. Simply run this command:

$ git push gerrit

Instead of pushing to git.eclipse.org (origin) this will push the change to review.mylyn.org (gerrit). Note that Gerrit creates one code review per commit. In case you committed multiple times see below how to merge commits.

Updating a Code Review

If an existing code review needs be updated with additional changes or if it needs to be rebased against the current master, checkout the branch and pull:

$ git pull

Then make the desired changes and instead of creating a new commit, amend the previous commit. This retains the change id and allows updating of an existing code review:

$ git commit -a --amend

To make the update visible on the server push again:

$ git push gerrit

This creates another branch that is automatically attached to the same code review.

Pushing Changes to Eclipse.org

Once a code review is approved in Gerrit, changes are automatically merged into the master. Here comes the quirk: In the case of review.mylyn.org this does not mean much. The Git repositories on review.mylyn.org are mirrored hourly from git.eclipse.org overriding any changes that were merged by Gerrit. For good reason, only committers are allowed to push to git.eclipse.org hence a committer needs to run this simple command eventually to make changes visible in origin/master:

$ git push origin

Contributors need to go through the standard Eclipse contribution process. Once a code a review is approved a patch needs to be created and attached to a bug report to track the IP in accordance with the Eclipse process. This is very easy using EGit’s drag’n’drop support for commits.

Squashing Commits

If you committed multiple times you can always squash commits later using interactive rebase, e.g. to merge the last two commits into one commit use this command:

$ git rebase -i HEAD~2

This opens an editor to modify the commit history. If you change “pick” in the second line of the editor to “fixup”, that commit will be merged with the previous commit when you exit the editor.

Accessing Gerrit through HTTP

If you are not able to connect to review.mylyn.org through SSH on port 29418 you can instead setup a password for HTTP access. In this case the url in the remote configuration needs to be modified slightly:

[remote "gerrit"]
  url = http://spingel@review.mylyn.org/p/org.eclipse.mylyn.tasks
  fetch = +refs/heads/master:refs/remotes/gerrit/master
  push = HEAD:refs/for/master

More Information

The Mylyn contributor reference has a lot more information on how to get started. I am looking forward to your code reviews and contributions to Mylyn!

4 Responses to “Contributing to Mylyn through Gerrit Code Reviews”

  1. Torkild U. Resheim Says:

    Thanks Steffen. I’m pretty sure this tutorial will come in handy for many of us. An especially when Eclipse.Org gets Gerrit support. Well done!

  2. Sascha Scholz Says:

    Thanks, Steffen, for the post and the setup of Mylyn Gerrit instance! Gerrit rocks! But you forgot to mention the Gerrit connector for Mylyn! ;-)

  3. Alex Blewitt Says:

    Thanks for the link to my tutorial! I also have some screencasts of using Eclipse EGit on my blog at http://alblue.bandlem.com/search/label/gerrit

    Note that since EGit 1.1 there is an option to clone from a Gerrit server, which includes the changeid setting and setting up the master accordingly.

  4. Steffen Pingel Says:

    @Torkild Thanks!

    @Sascha I thought that was old news already ;).

    @Alex Very good point. That’s certainly the easiest way to setup local Git repositories for Gerrit access when creating a new clone.

Leave a Reply