Code Review Tool Product Guide



Table of Contents:
  1. Concepts
  2. Logging In
  3. Dashboard
  4. Creating Reviews
  5. Reviewing
    1. Review Summary
    2. Changed Files
    3. Viewing Differences
    4. Identifying Issues
    5. Fixing Issues
    6. Verifying Fixes
    7. Completing Reviews
  6. Depots
  7. Account
  8. Searching
  9. Feedback
  10. Browser Configuration
    1. Tabs
    2. Popup
  11. Contact
1. ConceptsTop

Let's start with conceptual understanding of Code Review Tool. Code Review Tool uses the following concepts:

A reviewer can be in any of the following states:



A review can be in any of the following overall states:


2. Logging InTop

To login in enter your user name and password and click "logon" button. Check "remember me" check box if you don't want enter your user name and password again for subsequent visits.

Note: If windows integrated login is configured for your installation, you will not see a login screen.

Once logged in, you can log off using "log off" link on the top left. After successful login you will see your dashboard.

At the top of the page, the header contains the following menu items:

3. DashboardTop

Dashboard lists all the reviews you are associated with either as an author or reviewer.

You can filter the reviews you are interested in by using "Filter By:" drop down box at top right using the following criteria:

  1. Recent Reviews: Shows you the recent 50 reviews you were associated with irrespective of the review's current state.
  2. Assigned Reviews: Shows you the reviews which are assigned to you, as a reviewer, and the review state is "open".
  3. Created Reviews: Shows you the reivews which are created by you, as an author, the the review state is "open".
  4. All Reviews: Shows you all the reviews you are associated with irrespective of the review's current state.

You can sort the reviews by using "Sort By:" drop down box at top right using the following criteria:

  1. Modified On: Sorts the reviews in descending order by review's modified date and time.
  2. Created On: Sorts the reviews in descending order by review's created date and time.
  3. Status: Sorts the reviews by review's overall status.
  4. Title: Sorts the reviews in ascending order by review's title.
  5. Discussions: Sorts the reviews in descending order by number of discussions associated with review.

You can select reviews by clicking check box associated with each review record. Following actions are available for selected reviews:

  1. Select All: Selects all the reviews.
  2. Clear All: Clears the selected reviews.
  3. Show Details: Opens review details page in separate tab for all selected reviews.
  4. Edit: Opens review details edit page in separate tab for all selected reviews.
  5. Delete: Deletes the selected reviews after confirmation.
  6. Start: Starts the selected reviews as an author.
  7. Cancel: Cancels the selected reviews as an author.
  8. Close: Closes the selected reviews as an author.
  9. Review: Starts reviewing the selected reviews as a reviewer.
  10. Decline: Declines reviewing the selected reviews as a reviewer.
  11. Complete: Completes reviewing the selected reviews as a reviewer.

Open a review details by clicking "review details" link in the review record. To see all the discussions associated with a review click the discussions link, if any, in the review record.

4. Creating ReviewsTop

To create new review choose "new review" menu option at the top.

Select a depot from "Available Depots" drop down box. Once the depot is selected, the next drop down box "Depot's Recent Changelists" lists all the recent changelists for the selected depot. Select a changelist for review in the drop down box and click "Add" button. The selected changelist will be added to "Selected Changelist(s)" text box.

You can select multiple changelists from same depot or different depots. You can also enter the changelists for review manually using "{depotname}:{changelist number};" format. Multiple selected changelists are separated by ";". For example, "tfstest:789;perfdb:4954", lists two selected changelists, first changelist '789' from 'tfstest' depot and second changelist '4954' from 'perfdb' depot.

After selected changelists, select as many reviewers you want. Reviewers are users who will review the changes and provide feedback using discussions. For self review, add yourself as a reviewer. While selecting reviewers, the auto-completion helps you quickly search and select the appropriate reviewers.

Enter the optional title for the review in 'Title' text box. If no title is entered, a title is auto genrated using the selected changelist's details. Enter the optional description for the review in 'Description' text box. If no description is entered, a description is auto generated using the selected changelist's checkin description.

After entering details, click 'Save' button to create the review. You will see review creation progress.

5. ReviewingTop

Once a review is created, review details page shows the full details of the review.


5.a Review SummaryTop

At the top of review details page is review summary which summarizes following relevant details about the review:

If you are an author, in review summary, you can change the overall status of the review using following action links:

Once you select an action to change overall review status, the overall review status will be updated inline.

If you are a reviewer, you change change your reviewer status for the review using following action links:

Once you select an action to change your reviewer status, your review status will be updated inline.

Below the review summary box, following actions are available to manage the review:


5.b Changed FilesTop

Below the review summary, the changed files from across selected changelists in the review are displayed in a table.

The files table doesn't list all the files from different select changelists. It lists only effective files. For example, lets assume you include following two changelists with changes:

In files table, the changed files across changelists are grouped together. The common files across changelists are shown only once with combined difference between the oldest and newest version of the file across selected changelists. For the above example, the files table would be:

Files table has the following columns:

Files table provides the following actions:

You can sort the file table using "Sort By:" drop down box at right with the following criteria:

  1. Name: Sorts the files in ascending order by changed file name.
  2. Differences: Sorts the files in descending order by amount of differences between two versions.
  3. Discussions: Sorts the files in descending order by amount of discussions.
  4. Type: Sorts the files by type of the change.

To open details of a changed file, click the name link in the file record. To open list of discussions in a changed file, click discussion links in the file record.

Once you open details of a changed file, you are shown changed file summary at the top and changed file differences after summary. While reviewing, this is the page where you as a reviewer will be spending most of your time looking at source code changes and starting new discussions and responding to existing discussions.

At the top, changed file summary lists the following details:


5.c Viewing DifferencesTop

The file differences are either shown in "Top Bottom" or "Side/Side" diff view. The default difference view is selected based on your profile settings. You can switch between alternate difference views by selecting "Diff View" link.

The inserted lines are shown with light green background where as the removed lines are shown with light pink background. Similar lines are shown with white background. Both inserted and removed lines are also highlighted with darker font.

Difference view contains the following columns:

Differences view show summarized diff if its enabled. In summarized diff view, long sections of similar lines between source and destination file are hidden with a summary section with some context lines at the start and end of the section. This allows reviewers to easily concentrate on the differences rather than common portions.

If you hover your mouse over the summary section, it would show details on how many similar lines are hidden in the summary section. You can expand the summary diff section by clicking it.

To allow you to do productive reviews following keyboard shortcuts are available on the differences views:


5.d Identifying IssuesTop

As an author, to start a review click 'Start' link next to the overall review status. When a review is started, the review status changes to "In Review" and it becomes visible in associated reviewer's dashboard.

As a reviewer, to start reviewing a request, click 'Review' link next to your individual reviewer status. When you start reviewing a request, your reviewer status changes to "In Review".

As a reviewer, once you start reviewing a request you can start discussions across any changed file in the review. To start discusions:

  1. Open the appropriate changed file in differences view.
  2. Select the line or set of lines you would like to comment about.
  3. Right click and select "New Discussion" menu item or action link, for new discussion dialog.


  4. Enter your comment and click 'Create' button to create a new discussion.


  5. After successful creation of the discussion, you would see an hint for the presence of discussion in differences view.

    You can expand the discussion in the difference source view inline by clicking the discussion icon on the left.

You can start multiple discussions across a single changed file and across multiple changed files.

As a reviewer, once you are done reviewing all the changes and created necessary discussions to identify potential issues, you can mark the review request as complete by clicking "Complete" link next to your reviewer status. Once a reviewer marks a review request as "completed", all the discussion threads started by the reviewer are published and author of the review can see the discussions threads and respond to reviewer concerns. A reviewer can redact an unpublished discussion.

A discussion thread can be into states:

Only a reviewer who creates a discussion can change the status of that particular discussion from "open" to "closed". This allows reviewers to control the status of the identified issues represented as discussions.

Once a reviewer completes the review request, the reviewer's review status changes to one of the following:


5.e Fixing IssuesTop

Once a reviewer completes a review request, the author of the review can go through all the discussions started by the reviewer. The author responds to the open discussions in one of the following ways:

Once the author has responded to all the discussions and updated source code to fix the issues identified he needs to update the review so that the reviewers can verify the fixes. To update the review, author chooses 'Edit' review link in review details page and then just adds the additional changesets which contain the fixes and then clicks 'Save' button.

Code review tool now updates the review with latest changed files from new changelist. The discussions which were started by reviewer on the old versions of the file are now automatically migrated to newer version of the files. This allows the reviewers to easily verify the issues they identified in previous version of the changes over the new version of the changes.


5.f Verifying FixesTop

After responding to discussions and updating review with source code, the author restarts the review again by clicking "Start" link associated with overall status of the review. This allows the reviewer to verify whether the identified issues have been take care of or not.

To verify the fixes, as a reviewer you again start reviewing the review request by clicking 'Review' link. After than you can directly go through all your previous discussion threads by switching to 'Discussions View'.

You can look at all the discussions of review by clicking discussions link in review summary.

You can also look at the discussions of a particular changed file in review by clicking the discussions link in changed file record in changed files table in review details page.

Let's switch to review's discussions view. It contains review summary block at the top and discussions table at the bottom. The discussions table lists each discussion associated with a changed file in review as a record.

You can filter the discussions you are interested in by using "Filter By:" drop down box at top right with the following criteria:
  1. Open: Shows you the active discussions which in open state.
  2. Closed: Shows you the active discussions which in closed state.
  3. Latest: Shows you the active discussions which in either open or closed state.
  4. Migrated: Shows you the inactive discussions in old version of the files which have been migrated over to newer version of the file.
  5. All: Shows you all active and inactive discusssions in any state.

You can sort the discussions by using "Sort By:" drop down box at top right with the following criteria:

  1. Comment: Sorts the discussions in ascending order by discussion's first comment.
  2. Change: Sorts the discussions in ascending order by changed file name in which the discussion is present.
  3. Location: Sorts the discussions in ascending order by discussion's location in changed file.
  4. Author: Sorts the discussions in ascending order by discussion's author (i.e. reviewer).
  5. Status: Sorts the discussions in order by discussion's state.
  6. Created On: Sorts the discussions in descending order by discussion's created date and time.
  7. Modified On: Sorts the discussions in descending order by discussion's modified date and time.

The reviewer can narrow on the discussions by sorting the discussions by Author using author's name. The reviewer can then quickly look the associated source for discussion by hovering mouse cursor over the discussion icon for a popup showing discussion details.

The reviewer can also expand the discussion record inline to see the discussion details.

The reviewer can also navigate to discussion details in a separate page by clicking the details link in discussion record.

The discussion details page contains discussion summary, the relevant source code and discussion thread. The discussion summary contains the following details:

Beneath the discussion summary there is a 'delete' link to delete the discussion if you are a reviewer who started the discussion.

Source code details in discussion details page shows the discussion overlaid over relevant portion of the source code across multiple versions of the changed file. This allows the reviewer to quickly verify how the author has fixed the issue by changing the source code by looking at the discussion overlaid over various version of the same file.

The whole discussion thread is shown below source code details and input textbox is available with a 'Add' button to reply to the discussion.

To quickly review the changes a reviewer can use 'Review Wizard' link from review details.

Review wizard takes the reviewer through each changed file one by one. The reviewer can navigate to the previous and next changed files by the links provided at above and below the changed file differences. The author or reviewer can start the review at the first changed file and complete the review at the last changed file in the list.


5.g Completing ReviewsTop

After verifying the fixes, the reviewer who started the discussion can close the discussion if the issue was fixed. If not, the reviewer can respond to the discussion detailing why he or she thinks the issue is not fixed. A reviewer can close the discussion in discussion table by selecting relevant discussion and using 'Close' action. A reviewer can also close the discussion using the 'Close' action associated with discussion state in discussion summary in discussion details page.

Once the reviewer has verified the fixes, he or she can complete the review request by clicking 'Complete' link associated with reviewer's status. Once all the reviewers complete with no further issues identified, the author of the review can close the review using 'Close' link associated with overall status of the review. Once a review is closed that particular will not show up by default on author or reviewer's dashboard.

6. DepotsTop

Depots simplify creation of post-commit reviews. Depot represent a collection of settings to access an existing project in a particular kind of version control system. Review authors create and manage multiple depots to access existing source code, which needs to be reviewed, for different products on different version control systems. Code Review Tool supports creating depots for the following different types of version control systems:

  1. Team Foundation Server
  2. Subversion
  3. Perforce
  4. Source Safe

Logically there are two types of depots:

Selecting 'Depots' link shows you list of all the depots with the following actions:

You can sort the depots by using "Sort By:" drop down box at top right on the following criteria:

  1. Name: Sorts the depots in descending order by depot's name.
  2. Type: Sorts the depots by depot's type, like Team Foundation, Subversion or Perforce.
  3. Owner: Sorts the depots in descending order by depot's owner (user) name.
Note: Public depots which configured by administrator and visible to all users have no 'owner' and cannot be edited in browser.

7. AccountTop

Account menu options provides users with the following options:

Profile settings allow user to view and edit their settings. Following settings are available:

To edit the profile settings click 'Edit' button and to save profile settings click 'Save' button.

For changing password enter the old password and new passwords and click 'Change Password' button.

Administrators can notify all users through an email using the 'Notify Users' form.

8. SearchingTop

Selecting 'Search' menu option takes you to the search page. You can search across changed files, changelists, discussions and reviews you are associated with either as a reviewer or author.

You need to use SQL query syntax for searching. To filter based on searchable object types use 'type:{objecttype}' keyword in search expression. Following object types keywords are available:

Search feature allows you search across the source code of the files in a review also. Some search examples are:

Each search result is displayed as a record displaying the summary of the object in the result. The summary contains all relevant details of the object returned and with a link to the details page of the particular object.

To search across source file contents in the review just search by the keyword you are looking for. For example, "public and class" search string. The search will return the list of changed files which contains the keyword. Open the source file difference using the details link in the search record and then use browser's search feature to locate the keyword occurrences in that particular file.

9. FeedbackTop

You can send your suggestions, queries and issues by using the 'Feedback' form. Just fill in the details and click 'Send' button. Your feedback will help us improve the product, we really appreciate your feedback.

10. Browser ConfigurationTop

Configure your browser using the following tips to do productive code reviews.

10.a TabsTop

Configure your tab settings in browser to open new tab window for link traversal for optimal user experience. Having multiple tab windows, each containing a different change details of a code review, side by side under main browser window allows you to group all windows opened for code reviews. Below are browser specific help links on how to configure browser tabs:

  1. Internet Explorer
  2. FireFox
10.b PopupsTop

Code Review Tool uses JavaScript to open windows based on user request, like opening all changes as part of the review to see differences. This could be sometimes blocked by your popup blocker. Add Code Review Tool site as an exception to the popup blocker to open these windows correctly. Below are browser specific help links on how to configure popup blocker:

  1. Internet Explorer
  2. FireFox
11. ContactTop

If you need further help with usage or need additional information regarding any features of the product, contact us at 'support@protiumsoftware.com'.

Code Review Tool website has more information about the product.