Blogs about Jazz

Blogs > Jazz Team Blog >

Reviewing code changes with Rational Team Concert

In the good old days, things were easy. You worked on a bug, modified a few lines of code and were done. No one was looking over your shoulder to check if your code was right. The best code comes late at night when you’re alone anyway. No tests to run and no continuous build that would catch all the regressions you may have introduced. I dare you to say that in your career you have never seen this situation… And I don’t need to know if you were the late at night breaking code genius developer or the early morning one trying to repair :-)

Luckily things have changed. Rational Team Concert makes it easy to ask one of your peers to review your changes when you close a defect. In the scenario below, a developer named Christophe has completed his work on a Task. He would like his teammate Tim to review his changes. Christophe goes to the Approvals tab in the Work Item editor and adds an approval for Tim.

Approval tab on work item editor

Tim receives a notification by email or through an RSS feed (e.g. in the Team Dashboard). He opens up the Task and goes through the summary and comments to get some context. When he understands what Christophe was asked to do, he switches to the Links section in the work item editor and opens the associated change sets.

Work Item links tab

After clicking Open, the Change Summary view lists all the files and folders that Christophe had modified in these change sets. Tim sees that Christophe has modified 2 files.

Change Summary

Tim double clicks on the first file named (or right click and ‘Open in Compare Editor’). A compare editor opens up, showing all the changes Christophe made to that file when all the three change sets are applied. The Change Summary view aggregates all the change sets to present a synthetic view of all the resources modified. It gives access to a compare editor that visualizes how all these change sets affect the selected file. Tim is satisfied with the changes to that first file.

Tim now reviews the second file, He likes some of the changes, but some others seem unrelated to the Task he is reviewing. In need of clarity, he decides to turn on the Details Pane.

Details pane

The Details Pane shows that Christophe modified in three change sets. The Dependency Graph tells Tim how these change sets relate to each other. Tim can also see the comment of each change set and he gets suspicious of the second one. He double clicks on that second row. He inspects in a compare editor how that particular change set affected (in isolation of the changes from the two other change sets). The code is manifestly incorrect and not related to that task. Tim rejects the Review and adds an explanatory comment for Christophe in the work item editor (with a @Christophe).

Christophe agrees with Tim and attaches a fourth change set correcting the bad code he introduced in that file (Christophe could also create a change set to replace all previous three change sets if things were really bad). He asks Tim to review again. This time, Tim is happy to approve.

Approving a review request

In this example, Christophe was a well behaved teammate. He asked Tim to review his changes. But what if Christophe is distracted and forgets to ask for a review? The answer is to customize the process to add appropriate rules that work for your team and industry. Customize the project area or team area that Christophe is part of (i.e. the project area or team area that owns the stream Christophe delivers his change sets to). Here are two popular preconditions to set.

  1. Require Work Items and Comments – to ensure Christophe associates a work item to every change set he delivers
  2. Require Work Item Approval – so that Christophe cannot forget to set a review request on the work items associated to the change sets he delivers

There are many fancy ways to customize the process to your liking. You can enforce that a certain copyright be included, control which role is required for a review, etc. Evan’s article Source Control process recipes for Rational Team Concert is strongly recommended.

The RTC clients for Eclipse and Microsoft Visual Studio have received multiple enhancements in 4.0.1 under plan item 218176. Have a look at the videos below! Change review is now done in a new Change Summary view. This view is largely equivalent to the old Change Explorer when used to review changes, with additional features such as the Details Pane. The Change Explorer is now primarily used to compare workspaces and streams. Each view is optimized for their respective workflows (change review versus comparison of workspaces and streams).

Video: Efficiently and safely review code with the new Change Summary view in RTC Client for Microsoft Visual Studio

Video: Efficiently and safely review code with the new Change Summary view in RTC Eclipse Client

When reviewing changes, it’s important to know the things you don’t know – to the extent possible.

  1. With the Change Summary view, the reviewer is clearly be made aware whether they can conduct a full review or if someone else needs to do it due to access rights restrictions on certain components, files or folders.
  2. The reviewer will also be able to efficiently and safely review aggregated changes to a file when the corresponding change sets build on top of each other. When they don’t, the view will direct the reviewer toward the Details pane to review contributions from each change set individually, with a dependency graph explaining how the change sets reviewed depend on each other (maybe a change set is missing and it isn’t a good idea to approve the review).

The word change set is repeated many times here. Change set under the microscope will give you a detailed picture of what a change set is about.

With RTC, your team has the freedom to conduct peer reviews as they see fit, or setup the strictest process rules to govern every aspect of it. Chances are you will aim for something in the middle, something that works best for your team and the industry you are in.