Code Review Tool

Given enough eyeballs, all bugs are shallow

- Linus' Law, according to Eric S. Raymond

Linden Lab maintains an instance of the ReviewBoard code review tool at codereview.secondlife.com to be used for reviewing any proposed changes to any of our open source projects.

Use of this system is limited to developers who have executed a Second Life Viewer Contribution Agreement. Any changes or comments posted to the tool are Contributions as defined by that Agreement.

For complete documentation, see the ReviewBoard User Manual.

Logging In

Access to the system requires that you set up an account, which you can do on your own from the login page or by going directly to the account registration page.

When creating your account:

• Please use the same user id that you use for Jira.
• Use the same email address that you use for the opensource-dev mailing list (if you do not, then the notices of reviews you post and comments you make will not be successfully sent to the list).
• Select the 'Viewer' group

You may find yourself on the account creation screen again after you log in, if so, just follow the My Dashboard link:

The Dashboard displays reviews and lets you select the ones of interest to you. See the full Dashboard documentation.

Post Code To Be Reviewed

Prepare your change in a local working hg repository. It will be easier to keep track of outstanding reviews if you commit your change to that repository before posting it for review.

Once you have a local copy of the change, there are two ways to post it for review:

• manually upload patch using the web page interface
• post-review command line tool

Either way, you must Publish Your Review before any other users will be able to see it or comment on it.

manually upload patch

To create a patch file that shows your change, execute the following command from the top level of your repository:

hg diff -c commit > PATCH

where commit is the revision identifier for your change (if you have not made any other changes, this can just be tip). If you have not committed your change, you can leave off the -c commit, but this is not recommended.

Follow the New Review Request link to begin manually creating a review:

This takes you to the form that lets you upload your patch:

Select the repository from which you forked/cloned your working repository (making the wrong choice here increases the chance that the patch will not apply cleanly), and upload the PATCH file in the Diff field. You usually will not need the Parent Diff upload field, and can leave it empty. Then push the Create Review Request button to upload your patch and create a Draft Review:

Fill out each of the fields:

Summary

The first line of your commit message should be perfect for this.

Groups

Enter viewer (it will auto-complete)

Bugs

The identifier for the Jira issue this relates to (this becomes a link to the issue, but you just need to provide the key)

Description

Describe the fix, not the issue. Explain the changes made (for example, why the new code is better than the old code) and how you arrived at that solution.

Testing Done

Optional, but very nice if you can provide useful information here.

You must Publish Your Review

post-review

There is a command line tool called post-review, but it is not very mature and whether or not it works can depend on how you created your mercurial repository. I plan to work on improving this asap - Oz

Publish Your Review

Until you Publish your review, only you can see it. When you do publish it, a notice is sent to the opensource-dev mailing list (and, optionally to any People whose codereview accounts you have selected).

Posting Failure

If you get a message like:

file "doc/contributions.txt" (r6f971899f351) could not be found in the repository

it means that you have posted a review based on a revision that does not appear in the repository. This happens when you have either based your review on a project repository that contains changesets not yet integrated to the repository you are reviewing against, or you have created multiple changesets in your repository, but have not given the tool all of the differences.

There are two ways to correct this problem; for either method, you must first determine the common base with the repository you are reviewing against. Run the command:

hg out base-repository --template '{parents|short}' --limit 1 

This is the base-revision in the commands below. You can then either:

Create a single diff file that shows all changes from the base to your current code

This is the correct approach if all the changes are yours and should be reviewed together. This single diff file is the one you should post for review.

To create the single diff:

     hg diff -r "base-revision" -r tip > file.diff

or

Create two diff files - One of the changes to be reviewed, and another for the preceding changes.

If my-base-revision is the parent revision of those you want reviewed,

Create the diff of the changes that are not part of what you want reviewed (called the "parent diff") by:

     hg diff -r "base-revision" -r "my-base-revision" > parent.diff

Create the diff to be reviewed by:

     hg diff -r "my-base-revision" -r tip > review.diff

The web page for posting a review has a separate upload field for the parent diff; this will allow the ReviewBoard to correctly display your diff without including the parent diff changes in the review.

Reviewing

To see the changes in a review request, select View Diff:

Whenever possible, comment by selecting specific lines of code; click and drag on the line numbers:

Enter your comment in the floater (remember to direct comments to the code, and not the coder), and press Save to record the comment:

When you've made your specific comments, you can edit the review as a whole and add any general comments by selecting Edit Review:

Click the Ship It checkbox if your overall opinion is that he change is ready to be integrated; leave it unchecked if your comments suggest additional changes that should be made.

When your review is ready to be read by others (including being forwarded to the requester and the mailing list), select Publish Review; until you Publish it, your review cannot be found.

You can also Save Review to preserve what you have done so far, but this does not make it visible.