Review Summary Screen

The Review Summary Screen is presented any time you're viewing a review that's not still in the planning stage. It is split up into several sections:

You will know that you're part of a review because it will show up in your Action Items list:

Most of the fields mirror the title and custom fields supplied by the review creator.

You might be able to Edit the title and custom fields by clicking the "Edit" button on the top right. To have permission to do this, you must be either a participant in the review or an administrator, and the review must be in progress (i.e. not canceled or complete), and the role rules for your role must allow you to do this. In this case, the Edit toolbar button lets you edit the fields. Otherwise, the button will be drawn disabled as shown above, and if you click it, an error message will explain why you can't edit the fields.

You might be able to Cancel the review. To have permission to do this, you must be authorized to do so by the administrator, and the review must be in progress (i.e. not already canceled or complete). In this case, the Cancel Review button is drawn disabled, and if you click it, an error message will explain why you can't edit the fields.

Warning: Once a review is canceled it is canceled forever. You will have to create a brand new review. Users will still be able to find this review when searching and can view it in a read-only capacity, but the review cannot be restarted.

You might also be able to Re-open a review after a review is finished. You must be allowed to do so by the system administrator. In this example above, the user has the ability to reopen the review. However, if it is not allowed, the button will be drawn disabled.

The Participants section lists all participants in the review, their status, and their role:

Each user is listed according to his role in the review. User names are drawn crossed out if that user has already indicated that they are finished with the review. Users with configured email addresses will be linked to their email address, and user's phone numbers are displayed in tool-tips.

Also given in parenthesis are user initials. Initials are used throughout the review interface to identify users without taking up the screen space to print out entire names. Initials are determined automatically for each review so that no two users conflict. In the example above, "Jason Cohen" and "Jorge Cordova" share the same initials, so their indicating initials are JaC and JoC. If no two users share the same initials, the standard two character initials will be given.

You might be able to Edit the participant list. To have permission to do this, you must be either a participant in the review or an administrator, and the review must be in progress (i.e. not canceled or complete), and the role rules for your role must allow you to do this. If you're allowed, the Edit toolbar button lets you edit the list. Otherwise, the button will be drawn disabled, and if you click it, an error message will explain why you can't edit the fields.

When you change the list, any users removed will receive a notification that they've been removed and any users added will receive a notification that they've been added. You can add or remove yourself from a review, and indeed this is the most common way to "hand off" a review to someone else.

Initially the log will be empty. As defects are created for the review as a whole or on individual files and line numbers, all defects are collected and listed here. For defects associated with particular files, links to that file and line number appears in the table for fast access. All defect custom fields are shown in the table.

When, as the reviewer, you've verified that a defect you found has been fixed, you can indicate this by clicking [Mark Fixed]. You don't want to delete the defect in this case -- it was still a defect -- but you need to indicate that "everything is fine now." The defect is then redrawn to reflect this:

You can mark the defect open again if you change your mind. Open the defect by clicking [Mark Open].

You can also externalize a defect if you want to indicate that the defect will be fixed sometime after the review is complete. In this case, it will be indicated by a green bug with a blue arrow icon as shown below:

Only certain participants will be able to mark defects fixed. Which roles are allowed to do this depends on the system configuration. Also the user that created the defect is allowed to mark it fixed, and administrators are always allowed to mark any defect fixed.

You can chat with other users about this review as a whole, rather than chatting on individual lines of code:

There's much to say about chat and defects, but this interface is identical to the one in the Review Chats, so please see that section for details.

The Review Materials section is the heart of the review: All files are displayed and users can view content and differences and chat and create defects on specific lines of code.

All of the materials are displayed separately in subsections: Version control uploads, individual file uploads, images, and so forth. In each case, you can see any applicable version control information (author, date, comments, changelist ID) and all the files.

Files are listed with full paths. If under version control, the version control server paths are listed rather than local hard drive paths -- presumably the version control server paths will make more sense to other users. In the screenshot above, the Subversion repository URL path is being used instead of some local file path. Click on a file or line number to open the content of that file along with all comments.

Also listed are metrics of how many lines have been added, changed, and deleted since the previous version in version control, with special cases for situations like added or deleted files. See screenshot above for examples.

Columns next to each file indicate which users have commented and what their current status is. A user that has clicked "Accepted" will show up as a check, as in the screenshot above with JC and BD on Controller.java. Regular chat is a talk bubble as shown for BD on TabControl.java. Red or green bugs identify issues as on line 132 of UserPrefs.java. Yellow bubbles as on line 132 indicate there is chat on that line that the current user has not yet read.

Any user can Download Files by clicking on that toolbar item. This downloads a ZIP file to the local hard drive containing all files with subdirectory structure preserved. This means you can test the proposed file changes locally: Just download the ZIP file and expand it in your own development environment. This is also useful in the single-committer model for when you want to actually commit the changes. This can take the place of a patch file.

Warning: Downloading files to your local hard drive can have unintended consequences. Make sure you don't have changes of your own that you're overwriting. Also, remember that the author of these changes might not be synched to exactly the same versions of all files in version control, so if your local test fails this might be the reason.

You can also download individual file versions from the diff viewer, but the Download Files toolbar link is the more common way because you get all files at once.

You might be able to Upload additional files to the review. You can do this any time using one of the various client components, or you can use the toolbar button to be prompted further or to upload a file from your local hard drive. This button might be disabled if the review is complete or if you are not a participant; click the disabled toolbar icon to get an error message explaining exactly why you cannot upload files.

When multiple changes have been uploaded, you have some options on how to display them:

There are two or three options depending on the features of the version control system (if any) associated with the file changes in question. They are:

•

Do Not Roll Up
All uploaded changes are displayed. Files are grouped with other files that were uploaded at the same time. In the case of version control systems with atomic changelists, this means files are grouped by changelist. For other version control systems, each uploaded file-list appears separately. This selection is the default behavior for SCM systems with atomic changelists unless the review creator has specifically requested the rolled up view.

To make verification of defect fixes easier, Code Collaborator hides, by default, changelists that appear to be reworks. In the case of version control systems with atomic changelists, these are subsequent uploads of the same atomic changelist with the file contents changed. For other version control systems, this is any changelist that contains a file that has been changed in a newer changelist. To show hidden changelists, click the "Show previously-uploaded changelists" link. To hide them again, click the "Hide previously-uploaded changelists" link.

•

Roll Up All Changelists
This is available when the version control system doesn't have the concept of an "atomic changelist" before files are checked in (e.g. Subversion, ClearCase, CVS). In this option, all uploads are "rolled up" into a single list of files. A "status" column lets you know the status of each file. For example, a file might have been uploaded originally but wasn't changed during the last upload; in this case the status would be "unchanged." If a file was changed since the last upload the status would be "reworked."

This is the default selection for SCM systems that have no atomic changelists and can also be made the default for a specific review by the review creator.

•

Roll Up Non-Atomic Changelists
This is available with version control systems that have atomic changelists after check-in (e.g. Subversion). In this option, atomic changelists (after check-in) are not rolled up but non-atomic changelists (before check-in) are rolled up. The "status" column lets you know the status of each file as described above.

This is the default selection for SCM systems have atomic changelists only after check-in.

When is everyone finished? When does the review move on to another phase? At the bottom of the overview screen is a "Moving On" section that allows each participant to say when he is finished with the review. It looks different depending on the phase of the review and the participant.

The example review gives a high-level description of the phases of a review and how you get from one phase to another. The "Moving On" part of the screen is where participants actually move reviews into different phases.

For example, here's an author during the Inspection phase. Notice how the author isn't allowed to complete the review; in this set-up the reviewers get to say when it's done:

In another example, a reviewer has looked at files and found nothing wrong. If he indicates the review is complete, the review is finished for good:

If there is unread chat above, you're not allowed to complete the review. This prevents users from saying they're done when in fact they haven't responded or at least read everything that has been said:

If there are open defects, the reviewers still indicate when the review is finished, and the text explains that the review will be going into the Rework phase rather than the Completed phase: