Monday February 11, 2008

webrev for OpenJDK: A code-review generator

Introduction

Webrev is a tool that has been developed internally at Sun over the years to help in the process of code-reviewing. What it does is extract information from a workspace and generate HTML pages highlighting all the changes. In short: it lists all the files that have been changed and provides several views of the changes.

So, when a developer wants to have his changes reviewed, he runs webrev, checks the output, publish it on a website then sends the link to potential reviewers. This has the advantage of providing a simple and common format for such reviews, which optimizes the time spent on them.

However it is tightly dependent on the Source Control Management System used, in our case, teamware (also known as codemanager).

With the advent of OpenJDK and the switch to Mercurial (hg) as a SCMS, it became necessary to update webrev to support the new environment. I foolishly (very foolishly) volunteered for the task.

To make a long story short, I looked at what the OpenSolaris folks were doing with webrev, since they also were on the process of switching to mercurial, but it turned out we had some divergent needs and constraints. The critical list being: OpenJDK needs a multi-platform tool and support for the mercurial forest extension. So, I forked the project and started 'fixing' webrev according to our needs. I thought it wouldn't take me too long (did I mention I was a bit foolish).

Anyway, it, of course, took much longer than any of us expected (partially thanks to a moving target), but with the help of all the hapless Sun's engineers who (sometimes unknowingly) tested the various versions for me, we now have a reasonable version of webrev. By reasonable I mean:

• Continued support for teamware (we still use it, you know)
• Support for mercurial
• Support for the forest extension
• Runs on Solaris, Linux, MacOS X and Windows (under the Cygwin environment)

So, how does it work?

The simplest way is to make changes in your workspace, cd to the top level directory and type 'webrev':

$ webrev
   SCM detected: mercurial

 No outgoing, perhaps you haven't commited.
      Workspace: /home/guest/MyWS
      Output to: /home/guest/MyWS/webrev
   Output Files:
        File1
                 patch cdiffs udiffs sdiffs frames old new
        File2
                 patch old
     index.html: Done.
Output to: /home/guest/MyWS/webrev
$

And voila! You have a subdirectory named webrev (as well as a zip file of it for easy transfer) which contains all the HTML pages needed for a code review.

Of course there are a bunch of options that let you specify, for instance, where to put the webrev, where the workspace is, which version to compare against. I've put together a small documentation page where you'll find the details on that.

Requirements

You will need a few other (rather standard) tools in your path for webrev to run:

• Korn Shell (aka ksh): this is a shell script that relies on a few Korn Shell idioms. It also expects to find it at /bin/ksh. Of course you can edit the first line of the script to change its location.
• awk (or gawk or nawk)
• perl
• jar
• zip

There is a bit of sanity checking done at the start, so it will most likely tell you if anything is missing

Grab it here

So now, just get your copy of webrev, give it a spin, and feel free to send me feedback and bug reports.