Meet EGerrit

Gerrit is not only the name of Dutch computer scientist Gerrit Blaauw (the key engineer behind the IBM System/360 project in the early sixties), Gerrit is also the name of one of the most popular code review tools. Just as Gerrit Blaauw made the successful case for the 8-bit computer architecture (as opposed to the popular 6-bit architecture at that time), Gerrit – the code review tool – furnished code review as an efficient collaborative software development on a large scale. Additionally, it significantly changed the way of collaboration among software developers in many capital open-source projects, such as Android, LibreOffice, as well as Eclipse. Gerrit closely integrates with Git and provides a web-based user interface. As we developers like to use top-notch IDEs, such as Eclipse, the integration of Gerrit with Eclipse would finally allow us to stop switching back and forth between Eclipse and a web browser showing the Gerrit review we are currently working on. Therefore, in the spirit of EGit, which addresses the seamless integration of Git with the Eclipse IDE, EGerrit aims to bring all the benefits of supporting the entire Gerrit review workflow within Eclipse. EGerrit is currently in the Project Proposal Phase and is soon to be born into the Eclipse Technology Project family; reason enough to have a look at the intents of EGerrit and investigate what to expect.

The Gerrit Code Review Workflow

Before we dig into EGerrit, however, we recap the main features and the workflow of Gerrit. If you are a seasoned Gerrit user though, you may safely skip this section.

Gerrit is built around a shared Git repository and manages each contribution to this shared Git repository as an own review. A review goes through the following states: A new contribution is in the “needs review” state until all necessary reviewers’ approvals are present, which is typically at least one review confirming that the contribution is approved; once they are present its state changes to “ready to submit” and can now be merged into the development branch. For improved traceability, the information of already merged reviews, including its associated discussions and revisions, is still accessible in Gerrit but the review is closed with the state “merged”. If the review decision, however, indicates that the contribution should not be merged, reviewers (or the authoring contributor) may change the review’s state to “abandoned”.

Figure 1: Gerrit’s web interface showing an open review with conflicts and related changes

In Gerrit, the unit of a review is always a single Git commit. This leverages a powerful mechanism of Git for code review since the developer may easily group changes into a logical units by simply putting them into consecutive commits. As each review concerns exactly one commit, review dependencies can also be derived from the dependencies of the respective Git commits: If an open review exists for a commit, and the same commit is the ancestor of a new commit that is pushed for review, Gerrit will mark the new review to be dependent on the review of its ancestor commit (cf. Related Changes in Figure 1). Gerrit relies on Git also to handle another important mechanism: If the commit of a review is modified (using git commit –amend), for instance because of reviewers’ comments, all depending reviews are obviously affected. Therefore, Gerrit may rebase the commits of the depending reviews on top of the changed ancestor commit with one click. If the rebase cannot be done automatically, due to conflicts, Gerrit will mark the review as conflicting (cf. Cannot Merge in Figure 1).

Figure 2: The Gerrit Code Review Workflow

Figure 2 illustrates the basic code review workflow of Gerrit. When developers wish to make contributions to the shared Git repository, they first clone the Git repository ((1) in Figure 1), or, if they have cloned it already, pull the latest version of the code base, and start their work by applying changes.

Once the changes are ready to be shared and reviewed, they are committed to the local Git repository ((2) in Figure 2), typically on top of a new branch dedicated to the respective feature to be contributed (featureX).

To publish a commit for review, the developer simply pushes the commit to the Gerrit server using the standard means of Git; that is, git push <gerrit-url/gerrit-remote-name> ((3) in Figure 2). Gerrit acts as a common Git remote repository. However, in contrast to a common Git repository, Gerrit opens a new review for each pushed commit with the initial state “needs review”. Optionally, the developer can explicitly add specific reviewers to the opened review.

Reviewers may now start their work either by going through the changes in the diffs shown in the web interface of Gerrit or by pulling the commit to be reviewed to their local repository ((4) in Figure 2). Therefore, Gerrit offers dedicated Git “refs” for each review and each revision within a review. Thus, the changes of a review may be fetched using fetch <gerrit-url/gerrit-remote-name> refs/changes//.

Figure 3: The diff viewer with commenting capabilities of the Gerrit web interface

Once finished with the code review, reviewers may provide an overall rating ((5) in Figure 2), as well as add comments on lines in changed files using the web interface as shown in Figure 3.

As soon as the review is uploaded, the original developer is notified about the review results. Depending on the decision, the developer may happily enjoy the positive review or – and this is the more common case – improve his or her contribution by addressing the comments.  Once the developer is done, the changed files are amended to the original commit and again pushed to Gerrit, which will detect that this is a revision of an ongoing review (based on a change id in the commit message) and the process (steps (3) to (6)) starts over again.

Gerrit offers another neat feature: it provides specific hooks that, for instance, allow you to start the build and automated tests of the pushed commit on a continuous integration server ((7) in Figure 2). The continuous integration server may act as an automatic reviewer and add the results of the build to the review. If the build and the automated tests succeed, it adds a +1 Verified rating to the review.

Finally, if all necessary reviewers’ approvals are added to the review, which is usually configured to be at least one +2 code review and no -2 code review, Gerrit enables merging the commit into the development branch with a single click ((8) in Figure 2).

Why Integrating Gerrit with Eclipse? Why EGerrit?

While the web interface of Gerrit is simple and straightforward to use, there are several reasons why a tight integration with Eclipse makes the reviewers’ and contributors’ task a more enjoyable one. To begin with, there simply is no better way of reading and browsing through code than using the top-notch IDE we are all used to working with everyday. Syntax highlighting, code navigation, such as jumping to classes or method declarations, problem markers, and other features of the Eclipse IDE are as valuable for code review as they are for software development itself. Furthermore, many reviewers’ tasks, such as investigating the effects of a change, also require stepping through the code with a debugger or running ad-hoc tests. All these features are available in the Eclipse IDE but not in the web interface of Gerrit. Needless to say, it is the switching back and forth between the Eclipse IDE and the Gerrit web interface to, for instance, add line comments to a review, which interrupts the workflow and makes the reviewing process more inefficient. EGerrit is hence a natural complement of the Gerrit web interface and aims at providing a more convenient way of performing reviews for users of the Eclipse IDE.

Some of the functionality of Gerrit has already been integrated with the Eclipse IDE in the Mylyn Gerrit connector as part of the Mylyn top-level project. So why is starting another project with partly overlapping goals a good idea? First of all, diversity and the freedom of choice is what makes open source unique and awesome. Mylyn is great and also the Gerrit integration within the Mylyn reviews sub project offers very useful features. However, the major goal of the Mylyn reviews is toat some point, provide generic means for integrating code review systems. In contrast the primary goal of EGerrit is to achieve feature parity with the Gerrit web interface. While generality is a good thing, implementing an outstanding integration of Gerrit within the Eclipse IDE is challenging enough on its own without having to worry about a generic framework and a generic workflow. Eventually, feature parity with Gerrit and providing a generic review framework are competing, incompatible goals. Following the same spirit as EGit for integrating Git, EGerrit is a dedicated project with the clear focus on providing a high-quality integration of Gerrit and only Gerrit – including its specific interfaces, protocols, and workflows, which made Gerrit as popular as it is right now.

EGerrit: What to expect

EGerrit intends to provide feature parity with the Gerrit web front-end, supporting Gerrit version 2.9 and higher. It targets novice Gerrit users who are seasoned Eclipse users, as well as experienced Gerrit users who are new to Eclipse. EGerrit focuses on the developers’ needs in their day-to-day code reviewing tasks and aims at increasing the developers’ productivity when performing code reviews as well as receiving feedback from ongoing reviews as a contributor who pushed a change. Gerrit’s administrative tasks, such as user and project administration in Gerrit, are left out for now, as integrating these tasks with Eclipse would only bring limited value in comparison to performing such tasks in Gerrit’s web interface.

Figure 4: Mockups of the EGerrit user interface

From a user perspective, EGerrit consists of a dedicated Gerrit change viewer and a Gerrit dashboard view (cf. Figure 4). The dashboard view is a direct integration of the dashboard available in Gerrit’s web interface, which gives a great overview of reviews of interest. The EGerrit dashboard will also allow to perform queries over reviews with the same query syntax as in the Gerrit web interface, e.g., status:open (reviewer:self OR owner:self). It will give you the list of open reviews to which you are either assigned as a reviewer or which you have pushed for review yourself as a contributor. Obviously, double-clicking a review in the EGerrit dashboard will open up EGerrit’s change viewer.

The change viewer features four tabs: Summary, Message, Files, and History. The Summary tab provides all relevant meta information from a change under review at a glance, such as the state of the review (Needs Code-Review), the project and the target branch, the reviewers and their votes, as well as related and conflicting changes. Depending on the state of the review, the Gerrit change viewer enables users to submit, abandon, and rebase the change, as well as to checkout, pull, or cherry-pick the change into the local workspace with one click. Wherever necessary, these actions will be integrated closely with EGit. The Message tab shows the commit message and potentially allows you to modify it directly.

Figure 5: The diff viewer of EGerrit

The Files tab will probably be one of the most important tabs as it presents the list of files that have been changed with this commit. From there you can open up the diff viewer, to investigate the fine-grained differences of each file. The EGerrit team plans to spend a significant effort on providing a diff viewer within the Eclipse IDE that provides several of the popular features available in the Gerrit web interface, such as the line-by-line way to show changed lines. Instead of drawing connector lines between the left- and right-hand side text blocks, as it is currently with the diff viewer in the Eclipse IDE, corresponding lines will be aligned on the same horizontal position and blank lines will be shown if on the opposite side a line has been added or deleted, respectively (cf. Figure 5); this has the effect of a cleaner look in case of many changes. The diff viewer will also feature the differences among different versions, such as among different revisions of the same change as well as to diff against the current workspace version, etc. In EGerrit’s diff viewer, also the functionality of adding and viewing line comments will be integrated. Moreover, it will provide different means of navigating through the diffs, such as file-by-file, change-by-change, and comment-by-comment. Finally, the History tab will list all the updates of a review, such as new comments and ratings, new revisions (called patch sets in EGerrit), etc.

Another aspect in the focus of the EGerrit team is performance. A clever design of the data exchange protocol between the EGerrit client and the Gerrit server is key to efficiently working with Gerrit in Eclipse. Therefore, different strategies will be investigated to figure out the optimal amount of data to be pre-fetched and cached to ensure a fluent and responsive user interface, while at the same time avoid a lack data synchronicity between the data cached in the client and the data that is stored on the Gerrit server.

Outlook: Model Review

We are also very happy to announce that EGerrit will be the home of the review capabilities for EMF models that we plan to develop as part of the joint Collaborative Modeling Initiative. The model review extension of EGerrit will allow users to use Gerrit seamlessly also for changes that involve EMF-based models.

Figure 6: Initial prototype for model review

That includes reviewing model changes with EMF Compare instead of the text diff viewer, as well as annotating changed models with model-based comments that are linked to model elements in contrast to lines (cf. Figure 6).

Figure 7: Initial prototype for UML model review

Besides model-based comments that can be added and viewed in the generic tree-based editor of EMF, we also plan to provide extensions for showing and editing comments in GMF and Papyrus diagram viewers. Therefore, these extensions will also be capable of providing dedicated notations, which specify how the comment should be visualized. For instance, in Papyrus UML diagrams, we plan to reuse the notation of UML comments for review comments to ensure a familiar look and feel. Needless to say, the information on the comments and their positions on the canvas will be saved alongside the review and not inside the model under review (cf. Figure 7).

Conclusions

In summary, there is a lot to look forward to as EGerrit evolves and grows up into a mature part of the Eclipse tooling family. Given the current popularity of Gerrit in general and in the Eclipse community in particular, dedicated and optimized support for Gerrit is certainly something that may have a significant impact and a large number of potential users. As always, it is hard to say when we will see a first stable release. The EGerrit team announced the second quarter of 2015 for an initial version. We are definitely looking forward to the results, continue our work on integrating model review with EGerrit early on, and we will definitely keep you posted on the overall progress. Keep an eye on the Collaborative Modeling Initiative and the EGerrit project proposal web page.

https://eclipsesource.com/images/c4afe7a28f_02.jpg does not exist

Guest Blog Post

Guest Author: Philip Langer