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:
- Register an account at review.mylyn.org using an Open ID provider such as Google
- Define a username
- 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!
