Gallery2:CodeReviewTips - Gallery Codex
Personal tools

Gallery2:CodeReviewTips

From Gallery Codex

Code Reviews

Gallery is using a Code Collaborator server at http://reviews.gallery2.org for code reviews. We refer to it as ccollab or reviews.gallery2.org.

Review Process

Creating a Review

Say you made a change in modules/core/classes/GallerySession.class and wrote a corresponding unit test.

1. Using the ccollab client, this call will create a new code review and attach the changes to it:
cd gallery2
ccollab addchanges new modules/core/test/ modules/core/classes/
2. Then it will scan the given folder names (modules/core/test/ and modules/core/classes/ recursively for changed files) and prompt you to confirm the list of changed files in a text editor that opens automatically. Save the file and close it to confirm.

Then the client will upload the files and attach it to the review.

3. Browse to http://reviews.gallery2.org and it will show you all active / open reviews that you're involved in. Click on the new one that was just created.
4. Add a title, purpose and description. And then specify yourself as author and add another user as reviewer.
5. Finish the creation by entering the inspection phase (click the button). The designated reviewers / observers will get a notification email at that point.

It is recommended that you give a detailled description of your change and that you add comments to the code review files where you can anticipate unclear points. A short comment might save your reviewer a lot of time trying to figure out why something wasn't done in another way.

Reviewer and Author Roles

  • The author is the person that usually creates the review and adds changed files.
  • Reviewers review the code changes for correctness, style, security, etc. They add comments in case something isn't clear or needs discussion and file defects if they found a problem that should be fixed before the code can be committed to SVN.

In the process of a review, there can be multiple rounds of the reviewers filing defects and adding comments and the author responding with replies and new versions of the changed files.

As a reviewer, each time you're done with reviewing, you should click the "Finish" button. Note that if you click on the "Finish" button at a point where there are no unanswered comments / open defects, the review will be closed permanently.

Updating a Review

If you need to add additional changed files to the review, you can use the the ccollab client again. Say you need to update the changed files for review 44, you can do this with this command:

 ccollab addchanges 44 modules/core/test/ modules/core/classes/

It's the same command as the one we used before to create a review. The only thing that has changed is that we specify review id 44 instead of "new".

If you want to manually remove some files from the review, you can browse to the review at http://reviews.gallery2.org and in the "Review Material" section, click on the "upload" link to manage the existing files.

Finishing a Review

Once there are no unanswered comments and all defects have been marked as fixed, the review can be closed by the reviewers. Clicking finish will close the review permanently at that point.

The author can then check-in the change to Gallery's Subversion repository. If applicable, please include the task or bug id as well as the review id in the commit message.

Initial Setup

Before you can profit from the automation that is provided by the code review server, you need to configure a few things:

1. Create an account at http://reviews.gallery2.org/
Note: When logging in at reviews.gallery2.org for the first time, leave the password field blank. Then change the password once you're logged in.
2. Install the ccollab client (link to client and instructions at http://reviews.gallery2.org/)
3. Configure your client:
ccollab set scm svn
ccollab set collab http://reviews.gallery2.org <username> <password>
Note: Users of Eclipse might want to use the ccollab Eclipse integration (http://eclipse.smartbear.com).

Also see: Code Collaborator Feedback for known issues, workarounds, instructions, ...

Best Practices and Tips

  • Use the ccollab client
  • "~url review 20" gives you the URL to code review 20 in #gallery
  • A number in review descriptions is automatically converted into a link to sf.net's bug tracker.

Code Review Tools

review.pl

A useful perl script written by Bharat. This script will take files given on the command-line and print them to screen with a small header. Each line of the file is prepended with "> " to allow for easy commenting by the reviewer. If you don't specify a file list, it'll review every file under the current directory (excluding Subversion files).


Script:

#!/usr/bin/perl
use strict;

my @files = @ARGV;
if (!@files) {
  chomp(@files = `find . -name .svn -prune -o -type f -print`);
}

foreach my $file (@files) {
  $file =~ s|^\./||;
  print "=" x 30, "\n";
  print "$file\n";
  print "=" x 30, "\n";

  open(FD, "<$file") || die;
  while (<FD>) {
    print "> $_";
  }
  close(FD);
  print "\n";
}


Example 1: Prepare a single file for review

[ /home/signe > review.pl .cvsrc 
==============================
.cvsrc
==============================
> cvs -q -z3 -e vim
> diff -du
> update -Pd
> checkout -P

Example 2: Prepare all files in the current directory

[ /home/signe > review.pl
==============================
.cvsrc
==============================
> ...
> ...
==============================
login.txt
==============================
> ...
> ...

Repair Indention

File:Repair-indention.zip

For casual developers it's often quite hard to understand our indention style. This script helps to fix the indention in an automated way.