Getting a contribution accepted into Eclipse is not a walk in the park. In the Mylyn project, each patch that comes in through Bugzilla is reviewed by a committer usually going through multiple iterations until it makes its way into Git or CVS. Mylyn has great support for handling patches, but this can still be a tedious process for both the contributor and committer when it comes to larger changes, due to a lack of automation of the contribution workflow. Contributors need to keep patches up to date, possibly juggling several outgoing change sets which can easily lead to incomplete or over inclusive patches. On the receiving end committers are burdened with validating patches and running tests which requires a number of manual steps. Conversations around patches happen through Bugzilla comments making it difficult to refer to particular lines.
These problems are not limited open source contributions. In many organizations, development follows similar work-flows often requiring use of several applications that are not integrated. This article introduces the new Mylyn connector for the open-source Gerrit code review system that helps automate onerous parts of the code review process enabling developers to focus on collaborative aspects and code rather than nit picking broken patches.
Gerrit is a web-based code review server for the distributed version control Git. When combined with Hudson/Jenkins it forms a powerful system that stages and validates every change before other developers have even noticed. With the integrations available in Mylyn 3.6 and Mylyn Reviews 0.8 developers can now seamlessly integrate these tools in their day-to-day work-flows.
Alex Blewitt has written an excellent tutorial how to configure Git, Gerrit and Hudson. In this article we will assume that the following servers have been setup as described in the tutorial:
To get started we need to install the following tools from their respective p2 repositories into Eclipse:
- EGit – http://download.eclipse.org/egit/updates
- Mylyn Builds: Hudson Connector – http://download.eclipse.org/mylyn/latest
- Mylyn Reviews: Gerrit Connector – http://download.eclipse.org/reviews/updates
To illustrate the interactions in a typical code review we’ll look at how Alice and Bob work on on a code change together. We’ll start with Alice who intends to implement an enhancement for an existing project that is already setup in Gerrit and Hudson.
Alice has cloned the Git repository that is managed by the Gerrit server into her workspace. In her environment the server is called
By default EGit creates a configuration that pushes the local master branch to the remote master branch. For Gerrit, Alice needs to change the configuration to push the local master to refs/for/master instead. Gerrit uses that special location to stage changes for the master branch.
Alice is now ready to commit her enhancement and push it to Gerrit. The commit dialog has an option to automatically generate a Change-Id which is used by Gerrit to track the change. If Alice wants to update her commit later Gerrit can relate the changes based on that ID.
The confirmation dialog shows that the push to refs/for/master automatically created a new branch to track the changes for the code review.
In our setup we configured a Hudson server to monitor the review server for new branches. Every time a new branch is detected a build is automatically triggered. Alice now wants to verify that all tests pass in the build that was triggered by her push before involving Bob in the code review.
After Alice has configuring the build server in the Team Repositories view and subscribed to the corresponding Hudson job she can monitor the status in the Builds view without switching to the browser. Since Alice’s commit broke one of the integration tests the build status is red. This is not problematic since the commit is staged and not yet visible in the master branch.
It’s easy to drill down into the details of a failed build. Double clicking a job opens an editor that shows the failed tests, changed files and created artifacts. With a few clicks Alice can open test results in the JUnit view and re-run the failed test in her workspace.
Once Alice has fixed the bug she commits and pushes again to replace the previous change on the code review. To update the existing code review she amends the previous commit. That way, the commit message gets automatically populated with the Change-Id from the previous commit which identifies the code review. Through the ID Gerrit knows that the new commit replaces an existing change and is not a new code review.
Again, the build server picks up the changes and this time all tests pass.
Alice is now ready to pass the change on for review. She adds a task repository for the Gerrit server and a new query in the Task List.
The query is a personalized subscription to the review server. It brings in code reviews Alice is interested in into the IDE and enables her to work with them. Like any other Mylyn task, code reviews can be scheduled and activated embedding reviews seamlessly into the task-focused work day.
Code reviews open in an editor that is the hub for the conversation around a Gerrit change. The editor shows details about the work-flow state of a review, the people involved and the comments.
The review that is shown here has received one vote already. When the Hudson server executed tests it posted the results back to the review. A +1 in the Verified category indicates that the build passed.
To pass the code review a +2 is required in the Code Review category. To notify Bob that the change is ready for review Alice adds him as a reviewer in the people section.
Bob’s workspace is setup with the same projects and queries. When Bob task list refreshes a little popup notification is displayed and the review is decorated with a blue arrow in the task list.
Bob’s first step is to open the code review. The content under review is listed in the patch-set section. Each patch-set equals one commit to the Gerrit server and is tracked in a separate Git branch. Bob can now bring a patch set into his local workspace by using the fetch button under the patch set. This is useful to verify a fix or to try a feature through running changes locally. In this case Bob decides to review changes directly in the compare editor.
Double clicking a file in the patch-set section opens an editor that shows the current master on left and the proposed changes on the right. Comments can be added by selecting any line in the file and right clicking. Initially, comments are saved as drafts and are not visible to others.
After Bob has completed the review adding several comments he publishes them. The publish button opens a dialog that allows Bob to provide a rating.
With Bob’s +2 vote all requirements are satisfied and Bob submits the review as the last step. The most recent patch on the review is automatically committed to the master branch by Gerrit and becomes visible to all developers.
With these IDE integrations, Tasktop provides the same task-focused productivity benefits that developers already enjoy for tasks and SCM systems to code reviews and builds, capturing more of the developer’s workday and providing even better integration for mixed open source and commercial ALM stacks.
To see a demo watch the video at the end of Mik’s blog post on Mylyn 3.6.
About Steffen Pingel
Steffen Pingel is a Principal Software Engineer at Tasktop Technologies in beautiful Vancouver, BC. He enjoys working on tools that keep developers focused and productive and regularly speaks at conferences and user groups. He earned commit rights on the Eclipse Mylyn project in 2006 while completing his degree in Software Engineering at the University of Stuttgart. Since, he has become a member of the Eclipse Architecture Council and the Mylyn PMC and now leads several Mylyn sub-projects on Eclipse.org. Steffen is fascinated by the quality and extensibility of the Eclipse platform which keeps inspiring him to improve the Mylyn framework.