Introduction

My first project as a Google engineer was an internal web app for code review. According to Wikipedia, code review is "systematic examination (often as peer review) of computer source code intended to find and fix mistakes overlooked in the initial development phase, improving both the overall quality of software and the developers' skills." Not an exciting topic, perhaps, but the internal web app, which I code-named Mondrian after one of my favorite Dutch painters, was an overnight success among Google engineers (who evidently value software quality and skills development :-). I even gave a public presentation about it: you can watch the video on YouTube.

I've always hoped that we could release Mondrian as open source, but so far it hasn't happened: due to its popularity inside Google, it became more and more tied to proprietary Google infrastructure like Bigtable, and it remained limited to Perforce, the commercial revision control system most used at Google.

Fortunately, now that I work for the Google App Engine team, I've been able to write a new web app that incorporates many ideas (and even some code!) from Mondrian, and release it as open source. The Python open source community has been trying out Rietveld for the past few days, and has already been using it to do code reviews for Python (as well as providing valuable feedback in the form of bug reports and feature requests). Of course, the tool is not language-specific: you can use it for code reviews for any language!

Introducing Rietveld

To stick with the naming theme, I gave this new web app the code name Rietveld, after Gerrit Rietveld, one of my favorite Dutch architects and the designer of theZig-Zag chair. However, because most English speakers have trouble spelling his name correctly, the "live" web app is known simply as codereview.appspot.com.

The Rietveld app serves several purposes at once: it is a demo of fairly large-scale use of the popular web framework Django with App Engine, it makes some of the trickier (but portable) code we wrote for Mondrian available for reuse under the Apache 2.0 license, and it makes web-based code review available for many projects using Subversion repositories. Right now, any project hosted on Google Code can use Rietveld, as well as the Python subversion server. Support for arbitrary subversion servers is forthcoming.

While a public instance of Rietveld is running at codereview.appspot.com, organizations are of course free to run their own instance restricted and/or tailored to their own needs. That's what open source is for!

How Rietveld Manages Code Reviews

So what can you do with Rietveld? The basic workflow is:

1. Developer makes some changes in their Subversion workspace.
2. Developer uploads a patch in the form of svn diff output to Rietveld, using a small script named upload.py. This creates a new issue for them on the Rietveld website.
3. Developer goes to the issue that was just created on the Rietveld site, adds the email addresses of one or more reviewers, and causes Rietveld to send an email to the reviewer(s).
4. Reviewer navigates to the issue on the Rietveld site, browses the side-by-side diffs linked from there. A side-by-side diff shows the old and new version of the source code side by side, with deleted text on the left marked with a light red background, and inserted text on the right marked with a light green background. (Two different shades of red and green each are used, to highlight the differences at a finer-grain level than blocks of lines. This helps find one-character changes and clarifies diffs that just reflow a lot of text.)
5. Reviewer inserts inline comments directly into the side-by-side diffs, by double-clicking lines on which they want to comment. Inline comments are initially created in draft mode, which means that only the comment author can see (and edit) them.
6. Reviewer publishes comments, making them visible to everyone else, and sending an email to the developer (and to other reviewers) summarizing the inline comments with a little bit of context.

At this point, the developer can reply to inline comments directly on the Rietveld website using exactly the same mechanism as used by the reviewer. Replies simply become additional inline draft comments. The developer can also revise their code and upload a new version of the patch. The new version is attached to the same issue, and reviewers can choose to view the diffs afresh, or view the delta between the new and the old version of the patch. The latter feature is particularly helpful for large code reviews that require several iterations to reach agreement between developer and reviewer: the reviewer doesn't have to re-review stuff that didn't change between revisions and was already approved.

Coming Developments

I'm far from done with this application. Some features found in Mondrian that would be useful in Rietveld as well have not been implemented yet due to time constraints. The first users are also already asking for features I had never dreamed of, thanks to the many different styles of development found in the open source world. I have made the source code available as open source in this early stage in the hope to solicit outside contributions. My intention is to add outside developers to the project as soon as possible. As with Python, I am planning to remain in charge and review contributions carefully.

Links

Once more, codereview.appspot.com is the live web app, ready for your visits.

In the project home directory you can find some documentation and the complete source code.

For discussions, I've set up a Google Group: codereview-discuss.

In the bug tracker you can submit bugs and suggest feature requests.

Finally, here is the upload.py script mentioned above. Use Python 2.5.2 (or newer) to run it.