ReviewBoard - A tool I wish we had

When I look back, it isn't that we were not aware of some of the recommended processes nor did we believe that they were not useful. It is just that the development infrastructure was so poor that we could not effectively implement them. It really boiled down to too much effort for too little return.

These days, it is a shame if developers do not use some of these tools. Institutionalising some of these development tools makes it easier as each developer does not need to think about which to use. For example, these days, the default repository has become git although for a common development repository in contrast to a distributed environment, subversion is a perfectly good alternative. Since git can work in a centralised environment as well and is obviously an excellent tool, why spend effort to select between alternates.

Repositories can tie in with automated build systems, which will run the affected test cases and raise alert in case an update causes a regression error. The build automation still misses issues like there could be potential problems, security concerns or that there may be a better way to implement the code. How do we create an environment so that at least one person looks at the code?

ReviewBoard

It is great to see that ReviewBoard usage is increasing, including in a number of open source projects (http://www.reviewboard.org/users/). The original workflow of ReviewBoard was pre-commit, that is the code is reviewed before committing to the repository. However, it is possible to use the post-commit workflow, that is the code is submitted to the repository and then reviewed. The other very nice capability of ReviewBoard is that it can work with a fairly large number of repositories, including git and subversion.

Most people will find the pre-commit workflow to be the easier option. There is no ambiguity about the state of code in a repository. However, a programmer cannot work on the files which he has modified and are pending review. This may block him from working. In the post-commit workflow, there is the additional effort of keeping track of code in the repository which is still pending review. For repositories like git, it is fairly easy to create a branch and merge it after the review. You may want to look at how kde does it – http://techbase.kde.org/Development/Review_Board.

As a simple illustration, consider a centralised repository, e.g. subversion. In addition to the normal development environment, a programmer will need to install RBTools, which contain the command post-review. In a simple pre-commit scenario, a programmer:

  • Check out the code.

  • Make changes

  • Uses post-review command to submit the patch to be reviewed.

  • Signs into the web interface of ReviewBoard, associates a reviewer or a group of reviewers to the code patch and changes the state to needing review.

  • Modifies code as per reviewer's comments and updates the patch for review.

  • Once the code is reviewed and approved, commits the changes to the repository.

  • Finally, close the review request.

As a reviewer, the web interface will show the entries needing review. If a group of people may review the code, the review request will be shown to each member of the group. Each reviewer will continue to see the item needing review even if someone in the group has reviewed it. So, multiple people can review and offer their comments. However, if a review request needs to be reviewed by any one person from the group, the 'Number of Reviews' field in the web interface may be used to ignore requests which have already been reviewed but not yet closed.

Administering ReviewBoard

ReviewBoard is versatile. So, you will need to set it up for your needs. The basic requirements will be:

  • Add users. Authentication can be easily done using LDAP instead of a separate password for the application.

  • Create permissions for different types of users, e.g. submitters only, submitters and reviewers, reviewers with some administrative privileges, etc.

  • Add a repository.

  • Optionally, create default reviewers for various files.

ReviewBoard comes with a pretty good set of documentation for both users and administration. You can easily set it up and use it even if you are a small group.

It may not be a bad idea to use ReviewBoard even if you are the only developer. It gives you a chance to examine the changes you have made and have a chance to ask yourself – 'Why did I do that?'

Comments