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:
Click the image to enlarge it.
Click the image to enlarge it.
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
Click the image to enlarge it.
|
Item |
Description |
||
|---|---|---|---|
|
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 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.
|
|||
|
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. |
|||
|
Displays a list of actions for downloading review materials to your local computer. Downloads can be disabled by the administrator, in this case the 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.
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. |
|||
|
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. |
|||
|
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. |
|||
|
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: |
|||
|
|
|||
|
|
|||
|
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
|
Item |
Description |
|---|---|
|
|
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
|
Item |
Description |
|---|---|
|
|
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. |
|
|
|
Expands all the nodes in the Review Materials section. |
|
|
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
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:
|
|
Download a diff file for viewing in an external Diff Viewer. |
|
|
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 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
Click the image to enlarge it.
Review Materials
Web Client
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
|
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 |
|
|
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
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
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
|
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 |
|
|
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
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
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
|
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 |
|
|
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". |
