Open topic with navigation
Review page quick reference
The Swarm review page is used when reviewing changes:
- Log in to Swarm.
- To display the Swarm home page, click the Swarm Home
icon on the left of the main toolbar.
- If your dashboard is not already displayed, click the Dashboard tab.
- To open a review, click the ID of the review.
Jump directly to a specific area of the review page using the following links:
Review description
The review description is made up of the following elements (from left to right):
- Review ID: the unique number used to identify the Swarm review.
- Review author avatar: the review author's avatar, hover over the avatar to see the ID and name of the review author. Click on the avatar to go to the profile of the review author, see Viewing another user's profile.
- Review header:
- Review information: displays when the review was requested, the project branch the files are in, when the review was committed, and the changelist that the review was requested for.
- Mark all comments read button: click to mark all of the comments on this review as read, see Mark comments as read.
- Mark all comments unread button: click to mark all of the comments on this review as unread, see Mark comments as unread.
- Add Change button: click to add a changelist to the review. Options available depend on whether the review is pre-commit or post-commit. For information about adding a changelist to a review, see Add Change button.
- Download .zip button (if configured): click to download a compressed archive of all of the files in the review, see Download files as a ZIP archive.
- Deployment status button (if configured): indicates the success
or failure
of the review deployment. If your deployment system provides a URL to the deployment you can click it and view the deployment results.
- Test status button (if configured): indicates the success
or failure
of the review tests. If your continuous integration tests can provide a URL that provides details of a test run you can click it to view the test details.
- Review state button: indicates the current state of the review and is used to change the state of the review:
- Review states: a review can be in one of the following states:
- Needs Review: the review has started and the changes need to be reviewed.
- Needs Revision: the changes have been reviewed and the reviewer has indicated that further revisions are required.
- Approved: the review has been approved. The changes may need to be committed.
- Rejected: the review has been completed. The changes are undesirable and should not be committed.
- Archived: the review has been completed for now but it is not rejected, or approved. The review has been filed away in case it is needed in the future.
- Change review state: click the Review State button and select a new state from the review dropdown menu. State change options are only displayed if you are authorized to make the state change:
- Needs Revision: select to request changes to the files in the review.
- Needs Review: select to request further review of the changes.
- Approve (only available if the voting requirements for the review are satisfied. For information on voting requirements, see Required reviewers.): select to approve the review.
- Commit (only available for pre-commit reviews that have been approved): select to commit the review.
- Approve and Commit (only available for unapproved pre-commit reviews when the voting requirements for the review are satisfied. For information on voting requirements, see Required reviewers.): select to approve and commit the review in a single step, see Approve and Commit.
- Archive: select to archive the review.
- Obliterate Review (by default, only available for users with admin or super user rights): see Obliterate Review.
- Review description: the review description is automatically copied from the changelist that was originally used to create the review. To change the review description, by click the Edit Description
button.
- Add a Comment button: click to add a comment to the review description, view existing description comments, or hide existing description comments, see Commenting on a changelist or review description.
- Jobs (if configured): Perforce jobs can be linked to the review. For more information on Perforce jobs, see Jobs.
link: click to add a job to the review. Select the job from the dialog that is displayed. For more information on linking a job to a review, see Add jobs. - jobnnnnnn (where nnnnnn is the job number): click the job number to view details of the Perforce job. For more information about Perforce jobs, see Job display.
- Unlink Job
button: to unlink a job from the review, click the Unlink Job
button to the left of the job you are unlinking from the review.
Tasks, author, and reviewer area
The tasks, author and reviewers area is made up of the following elements (from left to right):
- Tasks
- Tasks list
button: click to display a dialog listing all tasks associated with the review. The task list can be filtered by task type, and tasks can be viewed from the task list, see Task list.
- Task Summary icons: shows a summary of the number, and status of comments flagged as tasks for the review. For more information about tasks, see Tasks.
- Red Flag icon: indicates the numbers of open tasks on the review.
- Green Check Mark icon: indicates the numbers of tasks that have been addressed on the review.
- Blue Double-Check Mark icon: indicates the number of tasks that have been addressed and verified on the review.
- Author:
- Reviewers:
- Edit Reviewer
button (if enabled): click to edit the reviewers for the review
- Up vote and Down vote count: indicates the number of up votes and down votes the review has.
- Groups: lists groups that are reviewers for the review. When at least one person in the group has voted, the avatar displays a badge indicating whether the group, as a whole, has voted up or down. Click on the group to see who has voted, and how they have voted, see Group reviewer.
- Individuals: lists individuals that are reviewers for the review. When an individual has voted on the review, their avatar displays a badge indicating whether they voted up or down. For more information about individual reviewers, see Individual reviewer.
- Your Avatar, located to the right of the reviewers: click your avatar to interact with the review. This allows you to join the review, leave the review, vote up, vote down, clear your vote, disable notifications for this review, make your vote optional, or make your vote required. For more information about interacting with the review, see Reviewers.
- Send All Notifications link: comment notifications are delayed by default, click to manually send the notification immediately for the review. For more information about comment notification delay, see Comment notification delay.
Files tab
Use the Files tab to view the files in the review and to see how they have changed using the Swarm view.
The Files tab is made up of the following elements (from left to right):
- Filter comments
button: click to limit displayed comments to those made on the selected review version.
- Review revision selectors: select which revisions of the review you want to diff. For details on using the revision selectors, see Select review revisions to view.
- Global diff view buttons (from left to right): control the initial diff view for all of the files in the review:
- Show Comments button: toggles the display of comments to inline in files or only in the Comments tab.
- Show Diffs In-Line button: displays all diffs as inline.
- Show Diffs Side-by-Side button: displays all diffs as side-by-side.
- Toggle Show Whitespace button: toggles the display of whitespace characters (such as space, tab, and newline) for all files.
- Toggle Ignore Whitespace button: toggles the highlighting of whitespace changes in all of the file diffs.
- Highlight whitespace changes: makes it easier to identify changes in file types where whitespace is important. This is the default value.
- Ignore whitespace changes: whitespace changes are not highlighted, this makes it easier to see the important changes in file types where whitespace changes are not important.
- Collapse All button: collapses all files
- Expand All button: expands all files. By default this button is disabled if there are more than 10 files in the review. For details, see Expand All Limit
Tip
The default states for the Show Comments, Show Diffs Side-by-Side, Toggle Show Whitespace, and Toggle Ignore Whitespace buttons are set in your user settings, see User Settings.
- File listing header:
- Comparing the files in the latest version of the review to Base or : displays the current version of the files in the review, the changelist that the review is based on, and the common path for the review files.
- Comparing two versions of the review files: displays which two versions of the review files are being compared, which changelists the files are in, and the common path for the files in both versions of the review.
- File change type icons: indicate the type of change for each file in the review:
-
-
Added/Branched/Imported
-
Edited/Integrated
-
Deleted
- File diff view buttons (from left to right): control the diff view for each individual file:
File diff view
Comments tab
The Comments tab is used to view all of the comments in the review.
Comment view
Comments are made up of the following elements (from left to right):
- Commenter avatar: the avatar of the user that made the comment, see Avatars.
- Commenter link: the username of the user that made the comment, click to see their user profile. For information about user profiles, see Viewing another user's profile.
- Comment context (only if the comment is made inline in a file): displays several lines of code before the line of code the comment is attached to. This helps makes sense of the comments should later changes remove those lines.
- Revision link (includes the file and line number if the comment is on a line in a file): click to go to the review revision the comment was made on. If the comment is made inline in a file the link will take you to that line in the file.
- Mark comment as read
button (unread comments only): click to mark a comment as read, the comment will only be marked as read for you. For more information on marking a comment as read, see Mark comments as read.
- Mark comment as unread
button (read comments only): click to mark a comment as unread, the comment will only be marked as unread for you. For more information on marking a comment as unread, see Mark comments as unread.
- Archive
button (only available for root level comments): click to archive a comment and any replies to that comment. For more information about archiving and restoring comments, see Archiving comments and Restore comments.
- Tasks: Flagging review comments as tasks is a lightweight workflow within a review that helps authors and reviewers prioritize review feedback. Any comment on a review can be flagged as a task, indicating to the review's author that the described issue needs to be addressed, and that the review is unlikely to be approved without a fix. For information about working with tasks, see Tasks.
- Not a Task
button: the comment has not been flagged as a task. Click to flag the comment as a task. - Flagged as a Task
button: the comment has been flagged as a task. Click to confirm that the task has been addressed, or to remove the task flag from the comment. - Task Addressed
button: the comment task has been addressed. Click to verify that the task has been addressed correctly, to verify and archive the task, or to reopen the task if it has not been addressed correctly. - Task Verified
button: the comment task has been addressed and has been verified as correct. Click to reopen the task you think it has not been addressed correctly.
- Comment content: this can be text, a URL, or an attachment. For more information about the content of comments, see Comment features.
- Reply link: click to reply to the comment. For information about replying to comments, see Reply to comments.
- Edit link (only available for comments that you have made): click to edit the comment. For information about editing comments, see Editing comments.
- Like
button (comments that you have not liked yet only): click to like the comment. The number to the left of the like button indicates how many users like the comment.
- Unlike
button (liked comments only): click to unlike the comment.
Add a comment
To add a comment, type your comment in the open comment text box at the bottom of the Comments tab page.
To reply to a comment, click the Reply button and type your comment in the comment text box.
- Comment text box: type your comment in the text box.
- URL links: to add a URL link to a comment, type the URL into the comment text box. The URL is automatically made into a link. For information about how URL links are displayed in comments, see Links in comments.
- Attachments: to attach a file to a comment, drag the file and drop it on the comment text box. For more information about attachments, see Comment attachments.
- Flag as a Task checkbox: select to flag the comment as a task. For more information about tasks, see Tasks.
- Post button: click to post your comment. The comment is posted immediately but the comment notification is delayed, see Comment notification delay.
- Post and Notify (x) link: click to manually post your comment and send the comment notification immediately.
Where (X) is the number of delayed comment notifications in the queue waiting to be sent, this number does not include the current comment you are working on.
History tab
The History tab presents a list of the events that affect this review.
Events include:
- When the review was started
- When a new reviewer joins the review
- When the review's state changes
- When the review's files are updated
- When a reviewer votes on the review
- When someone comments on the review, or one of its files
- When tests pass or fail, provided continuous integration is configured