Review Materials

Applies to Collaborator 14.6, last modified on October 04, 2024

The Review Materials section is the heart of the review. All the files are displayed here and participants can view content and differences and create comments and defects on specific lines or coordinates within a file:

Review Materials in Web Client

Click the image to enlarge it.

Review Materials in Visual Studio Extension

Click the image to enlarge it.

Review Materials in Eclipse Plug-in

Click the image to enlarge it.

Below, we will describe each of its elements in detail.

Toolbar

The toolbar of the Review Materials section holds the following items:

Web Client
Review Materials toolbar in Web Client

Click the image to enlarge it.

Item

Description

Upload

Displays a list of actions for uploading data to the current review. Uploads can be disabled by the review creator and by the administrator, in this case the Upload button is disabled as well.

The upload actions are:

<Server-side integration title> - upload changes from one of pre-configured source control repositories.

Files - upload arbitrary files from your computer.

Tip: Alternatively, you may just drag your local files and drop them to review web page.

Folder - upload all files and sub-folders from the specified folder on your computer.

Simulink Archives - Upload Simulink models that have been exported as web view archives.

URL - Attach live URL link.

Local Changes - upload local files using the command-line client, GUI Client, or P4V integration.

Download

Displays a list of actions for downloading review materials to your local computer. Downloads can be disabled by the administrator, in this case the Download button is disabled.

The actions are:

Files - download a ZIP file 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.

Downloading files to your local hard drive can have unintended consequences. Make sure you do not have changes of your own that you are overwriting. Also, remember that the author of these changes might not be synced 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 the files at once.

Diff - download a unified diff of all the files in the review.

Read

Allows to mark all comments in all review materials as read. Use with caution, as this operation makes it extremely easy for someone to mark all comments in all review materials as read without actually reading them. Therefore typically this action is disabled by administrators.

Edit files

Allows changing the list of review materials by hiding files that do not need to be reviewed. Hidden files will not be listed in the Files section and their content will not be displayed in the Diff Viewer.

By default, only review authors can hide files, and they can perform this only in the Planning phase. To learn more about this feature, see Hide Files From Review.

View as

Allows changing the format of how the review materials are listed. If a review contains only one changelist, this command is inactive. The view options are:

Overlay (default) - display all files from multiple changelists or uploads in one list.

Separate - display files from each changelist or upload in a separate list.

Display

Allows to filter not reviewed files in the review materials. The toggle is disabled for separate mode (no filtration in that mode to avoid of confusing behavior when there are some versions are marked as reviewed, but the latest version of file not marked). The display options are:

All files (default) - display all files from the review materials.

Not reviewed only - display only not marked as reviewed files in the review materials (for overlay mode only).

Visual Studio Extension
Review Materials toolbar in Visual Studio Extension
Review Materials toolbar in Visual Studio Extension

Item

Description

Upload

Invokes the Add to Review Wizard for uploading data to the current review. Uploads can be disabled by the review creator and by the administrator.

Eclipse Plug-in
Review Materials toolbar in Eclipse Plug-in
Review Materials toolbar in Eclipse Plug-in

Item

Description

View

Changes the format of how review materials are displayed. The following options are available:

Compressed Tree (default) - a single node represents the path to the file.

Tree - a tree of nodes represents the path to the file.

Flat - no hierarchy in representation of files.

Expand All

Expands all the nodes in the Review Materials section.

Collapse All

Collapses all the nodes in the Review Materials section.

Changelist info

The Changelist info section displays information about the uploaded files - who and when has submitted files, version control system, changelist IDs, commit messages, diff command and so on. Depending on how the materials were added, this information may vary a little.

Note: There is no Changelist info section in Eclipse Plug-in.
Web Client
Changelist info in Web Client

Click the image to enlarge it.

In Overlay view, this section combines information from each changelist, while in Separate view this section precedes each particular changelist. If the commit message is too long, or consists of multiple lines, then the message is trimmed at 70 characters. To see the full message, press the ellipses button. The section has two more buttons:

External Diff

Download a diff file for viewing in an external Diff Viewer.

Delete

Deletes a changelist from the review materials. If you have multiple changelists in the review, you will need to go to separate view in order for the button to be enabled. You cannot delete an arbitrary file from a changelist. You can only delete the entire changelist. You cannot delete changelists that have comments to any file. Ability to delete review materials can be disabled by review creator and by administrator, in this case the Delete button is disabled as well.

To exclude unneeded files from review, we recommend hiding files rather than deleting a changelist. Read Hiding Files From Review for details.

Visual Studio Extension
Changelist info in Visual Studio Extension

Click the image to enlarge it.

Review Materials

Web Client
File list
File list

The Files column shows the files in this review. This part of the screen may look different depending on the selected View as setting. The icon next to the file name indicates what operation was performed to the file.

Icon

Meaning

File was modified.

File was added.

File was reverted before the review has started.

File was deleted.

File was reverted during the review.

File was marked as reviewed.

To open the content of a file in the Diff Viewer and view all comments associated with that file, just click its name in the file list. In Overlay mode of review materials, Diff Viewer will display overall changes made to the file as specified by the Default Revision Comparison of Diff Viewer setting, while in Separate mode it will display changes made by a particular changeset.

The Utility column may precede the Files column, it groups various actions that could be performed over the specific file. For instance, it can display the Hide check boxes for hiding files, the Upload new version button for uploading new revision under a different file name, or the Delete latest version button for deleting the latest version of manually uploaded files. Admin has permission to remove it even when there are added comments or defects to the file. In this case all comments and defects will be permanently delete from Collaborator.

The Conversation column of the Files list shows where comments and defects have been made, their location within a file as well as whether these comments have been approved by other participants.

Conversation status icons and Location column
Conversation status icons and Location column

Icon

Meaning

This participant has made a comment.

This participant has clicked "Mark Accepted" for file revision or comment. When the author uploads new revision of a file, the icon will change back to denoting that the participant has not yet approved this new revision.

This participant has created a defect, which is currently "Open".

This participant has created a defect, which is currently marked as "Fixed".

This participant has created a defect, which is currently marked as "Rejected".

This participant has created a defect, which is currently marked as "Tracked Externally".

The Location column indicates where within the file the conversation represented by this row is located. Yellow alert bubbles () mean there is activity on that line that the current user has not yet marked read. Click on a line number to open the content of that file and view that conversation. When the respective document is being converted, the Location column displays conversion progress indicator instead.

Metrics, Status and Notes columns
Metrics, Status and Notes columns

The next three columns show the number of text lines or lines of code (LOC) that have been added, changed, and deleted, with special cases for situations like added or deleted files.

Icon

Meaning

The number of lines that have been added.

The number of lines that have been modified.

The number of lines that have been removed.

The lines of code metrics (LOC metrics) are calculated only for source code and other text-based files. For other types of review materials (Word, Excel, PDF or Image files) the metrics are not calculated and return 0.

If the Overlay view is selected (default), the LOC metrics are calculated comparing the latest uploaded revision of file against the baseline revision of that file. Here, the baseline revision stands for the revision at the moment the review was created.

If the Separate view is selected, the LOC metrics are calculated comparing each individual file revision against its previous revision.

For reviews created by pull requests, file changes made by merge commits (if any) are displayed in Separate view, but they are not taken into account when calculating overall LOC metrics.

The lines of code metrics and conversation positions are calculated including whitespace characters, letter-case changes and COBOL sequence numbers (if any). Diff Viewer has options to ignore those when displaying file difference. When these options are enabled, line numbers and conversation position displayed in Diff Viewer may vary from line numbers and conversation position displayed in Review Screen and reports.

The Status column shows how many times the file has been reworked during this review. For reviews created by pull requests, file changes made by merge commits do not affect the overall rework count of a file.

The Notes column allows any user to annotate the files. To edit the note click in the note column. This is typically used for messages to all reviewers such as "review this file first", or "ignore this file".

Visual Studio Extension
File list
File list

The Files column shows the files in this review. The icon next to the file name indicates what operation was performed to the file.

Icon

Meaning

File was modified.

File was added.

File was reverted before the review has started.

File was deleted.

File was reverted during the review.

To open the content of a file in the Code Viewer or Diff Viewer and view all comments associated with that file, just click its name in the file list.

The Conversation section of the Files list shows where comments and defects have been made, their location within a file as well as whether these comments have been approved by other participants.

Conversation status icons and Location column
Conversation status icons and Location column

Icon

Meaning

This participant has made a comment.

This participant has clicked "Mark Accepted" for file revision or comment. When the author uploads new revision of a file, the icon will change back to denoting that the participant has not yet approved this new revision.

This participant has created a defect, which is currently "Open".

This participant has created a defect, which is currently marked as "Fixed".

This participant has created a defect, which is currently marked as "Tracked Externally".

The Location column indicates where within the file the conversation represented by this row is located. Yellow alert bubbles () mean there is activity on that line that the current user has not yet marked read. Click on a line number to open the content of that file and view that conversation.

Metrics, Status and Notes columns
Metrics, Status and Notes columns

The next three columns show the number of text lines or lines of code (LOC) that have been added, changed, and deleted, with special cases for situations like added or deleted files.

Icon

Meaning

The number of lines that have been added.

The number of lines that have been modified.

The number of lines that have been removed.

The lines of code metrics (LOC metrics) are calculated only for source code and other text-based files. For other types of review materials (Word, Excel, PDF or Image files) the metrics are not calculated and return 0.

For reviews created by pull requests, file changes made by merge commits (if any) are not taken into account when calculating overall LOC metrics.

The lines of code metrics and conversation positions are calculated including whitespace characters, letter-case changes and COBOL sequence numbers (if any). Diff Viewer has options to ignore those when displaying file difference. When these options are enabled, line numbers and conversation position displayed in Diff Viewer may vary from line numbers and conversation position displayed in Review Screen and reports.

The Status column shows how many times the file has been reworked during this review. For reviews created by pull requests, file changes made by merge commits do not affect the overall rework count of a file.

The Notes column allows any user to annotate the files. To edit the note click in the note column. This is typically used for messages to all reviewers such as "review this file first", or "ignore this file".

Eclipse Plug-in
File list
File list

The Materials column shows the files in this review and the location of comments.

The icon next to the file name indicates what operation was performed to the file.

Icon

Meaning

File was modified.

File was added.

File was reverted.

The icon next to the comment indicates if the comment has been marked Read () or not ().

To open the content of a file in the Compare Editor and view all comments associated with that file, just double-click its name in the file list.

The Conversation section of the Files list shows the status of comments and defects.

Conversation status icons
Conversation status icons

Icon

Meaning

This participant has made a comment.

This participant has clicked "Mark Accepted" for file revision or comment. When the author uploads new revision of a file, the icon will change back to denoting that the participant has not yet approved this new revision.

This participant has created a defect, which is currently "Open".

This participant has created a defect, which is currently marked as "Fixed".

This participant has created a defect, which is currently marked as "Tracked Externally".

See Also

Review Screen

Highlight search results