Review page quick reference

Tip

The Swarm review page is described in this documentation.

The old review page is now referred to as the classic review page. To use the classic review page, use the Classic view toggle switch at the top of the review page.

The Swarm Classic view option will be removed in a future Swarm release.

Help for the classic Swarm review page is available in the Swarm 2021.2 documentation. See Review display.

The Swarm review page is used when reviewing changes:

  1. Log in to Swarm.
  2. To display the Swarm home page, click the Swarm Image of the Home icon icon above the menu.
  3. If your dashboard is not already displayed, click the Dashboard tab.
  4. To open a review, click the ID of the review.

By default, when you open the Review page for the first time, the file list panel and the information panel are hidden. Use the Show more context buttons to view the file list panel and the information panel.

For more information about the show more context buttons, see File diff panel.

Jump directly to a specific area of the review page using the following links:

Review description

Image of the Review Description Section

The review description is made up of the following elements:

  • Review description header:
    • Review information: Displays the following details:
      • Review author avatar and name: The avatar and name of the review author. Hover over the avatar to see the name of the review author and hover over the name to see the ID of the review author. Click on the avatar or name to go to the profile of the review author. See Viewing another user's profile.
      • Review type: Displays the review type, reviews can be pre-commit or post-commit.
      • Review ID: The unique number used to identify the Swarm review.
      • Review raised: When the review was requested.
      • Version: The version of the review being viewed and the total number of review versions.
      • Project branch: The project branch the review files are in, click to go to the project page.
      • Last updated: When the review was last updated.
    • Review state icon: 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.
    • Voting buttons: click a voting button to vote the review up or down.
    • Change state button: Click to 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.
      • Reject: Select to reject the review.
      • Archive: Select to archive the review.
    • Review actions Image of the Review actions button button: click the Review actions button to:
      • Add change: Select 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.
      • Download zip (if configured): Select to download a compressed archive of all of the files in the review, see Download files as a ZIP archive.
      • Change author (if configured): Select to change the author of the review, see Change the review author.
      • Obliterate review (by default, only available for users with admin or super user rights): See Obliterate Review.
      • Join review (only if you are not a member of the review): Select to join the review. If you vote on a review, you automatically join the review and become a reviewer.
      • Leave review (only if you are a member of the review): Select to leave the review.
      • Mark all comments read: Click to mark all of the comments on this review as read.
      • Mark all comments unread: Click to mark all of the comments on this review as unread.
      • Refresh projects: Select to check if the review files are associated with any projects created or updated after the review was last updated. If any projects are found that are not already associated with the review, the review is linked to them. See Refresh projects.
      • Disable notifications (only supported in the original Swarm review page): Select to disable notifications for this review.
      • Try it out (only supported in the original Swarm review page and if configured): If your deployment system provides a URL to the deployment, you can select it to see the deployment results.
  • Review description: The review description is automatically copied from the changelist that was originally used to create the review.

    When the review description size exceeds the 25% of the page, only the initial part of the review description is displayed. Select the Expand description button to view the full review description and select the Collapse description button to hide a part of the review description.

    To change the review description, click the Edit Description button image Edit button. Markdown content is displayed in the review description, but Markdown support is limited to prevent execution of raw HTML and JavaScript content. For information about Markdown, see Markdown in comments and review descriptions

    • Update pending changelist checkbox in the edit description dialog (only available if you are editing the description of a pre-commit review and you are the original author of the changelist that created the review): Select the checkbox to also apply your review description changes to the original changelist description.
  • Comments (n): Click to add a comment to the review description, view existing description comments, or hide existing description comments, see Commenting on a review description.
  • Jobs (n) (if configured): Perforce jobs can be linked to the review. Click to add a Perforce job to the review, view jobs linked to the review, unlink a job from the review, or hide jobs on the review. For more information on Perforce jobs, see Jobs.
    • Add a job: Click to add a job to the review. Select the job from the dialog that is displayed.
    • 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.
    • X button: To unlink a job from the review, click the X button of the job you are unlinking from the review.
  • Send All Notifications (n) (where n is the number of delayed notifications): Click to manually send all of your delayed notifications for the review. For more information about comment notification delay, see Comment notification delay.

Information panel

By default, when you open the Review page for the first time, the file list panel and the information panel are hidden. Use the Show more context buttons to view the file list panel and the information panel.

For more information about the show more context buttons, see File diff panel.

The information panel on the right side of the review page contains the following elements:

  • Blocking Approval or Blocking Commit:
  • Once a review has been approved, the Blocking Approval section is not displayed.

    For pre-commit reviews, if a user adds a new requirement to an approved review, then that requirement is displayed in the Blocking Commit section. For example, if a project initially has the Minimum up votes requirement set to one and this requirement is satisfied, and the review is in approved state. Now, if the Minimum up votes requirement changes to two then this requirement is displayed in the Blocking Commit section. Only when this requirement is satisfied the user can do a commit.

    • Pending Comment Tasks: Provides a list of pending review comments that are flagged as tasks. The pending comment tasks are shown only when the disable_approve_when_tasks_open configurable is set to true in the SWARM_ROOT/data/config.php file.

      Note

      If Swarm is configured to prevent approval of reviews with open tasks and a review has open tasks, the Approve, and Approve and commit options will not be available for the review. This option is configured by an administrator. See Disable approve for reviews with open tasks.

      To approve, or approve and commit a review with open tasks, you must address the tasks first and then set them to Task Addressed, or Not a Task. See Set a task to Task addressed or Not a task for details.

      For more information about approving a review with pending tasks, see Approve a review with open tasks.

    • Required Reviewers: Provides a list of all the Individual and group reviewers that are required to vote on the review. A review can not be approved or committed until the required reviewers have voted up on the review.

      A required Review page quick reference has a star badge over their avatar. A required Group reviewer either has a star badge or a star badge with a 1 over their avatar.

    • Blocking Tests: Provides a list of workflow tests that have Failed or have an In progress status that is blocking approval for a review. A review can not be approved or committed until the review author fixes all the failed tests. For more information about a failed test, see Review page quick reference.

    • Minimum Up votes: Provides the number of Minimum Up votes required for each project that you have access to. This includes the maximum number of Minimum Up votes required for all branches in a project blocking approval or commit for a review. For more information about Minimum up votes for a project see, General Settings tab. For more information about Minimum up votes for a project branch, see Branches tab.

      For private project, the maximum number of Minimum Up votes for all private projects and their branches that is blocking approval for a review is displayed.

    • Moderator Votes: Provides a list of branch moderators that are blocking approval or commit for a review. Depending on the configuration of moderator_approval configurable in the SWARM_ROOT/data/config.php file, the branch moderator approval is required. Ensure that the branch moderator approves the review and not just up votes it.

      By default, when a review spans multiple branches that have different moderators, only one moderator from any one of the branches needs to approve the review.

      Swarm can be configured to require that one moderator from each branch must approve the review, this is a global setting. If a moderator belongs to more than one of the branches spanned by the review, their approval will count for each of the branches they belong to. For instructions on how to configure moderator behavior, see Moderator behavior when a review spans multiple branches.

  • Reviewers:
    • Edit Edit Description button image 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.
  • Tasks
    • Task Summary icons: 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.
    • Show Task details Task list button image button: click to display the Tasks dialog listing all tasks associated with the review. The tasks can be filtered by reporter and task type, and you can change the task state directly from the Task dialog. See Task details.
  • Tests (if configured): displays the test results for the current review version in the information panel
    • Image of Tests passed icon Passed: Displays the number of the tests that have passed for the review version.
    • Image of Tests failed icon Failed: Displays the number of the tests that have failed for the review version.
    • Image of the Manual tests icon Manual: Displays the number of On Demand tests that can be run manually for the review version.
    • Image of Tests In Progress icon In Progress: Displays the number of tests that are running for the review version.

    Show test details Image of the Show test details button button: Click to view test run information for tests associated with the review version:

    Image of the List of tests

    If your continuous integration system calls back to Swarm with a URL, the test run is linked to the URL provided. If the test result contains any messages, click the Show more button to the left of the test to view them

    When the content of a review is unchanged between review versions, the tests are not rerun because the files have not changed. In this case, the earlier test results are displayed and marked with the word (Copy). You can manually run these tests if required by using the Run test button Run test button.

    The following actions are available from the Tests dialog for tests called by a workflow:

    • Rerun test: If a test has completed you can rerun the test, click Image of the Rerun test button to rerun the test for the most recent version of the review.
    • Run test: If the review workflow has a test set to run On Demand, click Run test button to manually run the test for the most recent version of the review.
    Tip
    • The Run test and Rerun test buttons are only available if you are logged in to Swarm, viewing the latest version of the review, and the test was called by a workflow.

    • The Rerun test button is not available for tests that are in progress.

    • When you click Run test or Rerun test, all of the buttons in the list are temporarily disabled while Swarm starts the test and checks if any other tests are in progress.

    • The Rerun test and Run test buttons are only available for tests that are run by a workflow. They are not available for tests that are run because they are configured on a project.

    Note

    Private projects: if a test for a private project is added to your review because Iterate tests for affected projects and branches is selected for the test, Swarm honors the private project's permissions and displays it as Private project in the test list to users that do not have permission to view it.

  • < (only displayed if the information panel is expanded): click to collapse the panel.
  • > (only displayed if the information panel is collapsed): click to expand the panel.

Files tab

Use the Files tab to view the files in the review and to see how they have changed using the Swarm diffClosed (noun) A set of lines that do not match when two files, or stream versions, are compared. A conflict is a pair of unequal diffs between each of two files and a base, or between two versions of a stream. (verb) To compare the contents of files or file revisions, or of stream versions. See also conflict. view.

Files tab image

Swarm supports stream specs in your workspace using the Private editing of streams feature. If a changelist or review contains a stream spec, it will be displayed first in Files with the prefix stream: //, for example: stream://MyStreamDepotName/MyStreamSpecLocationName. A changelist/review can only contain one stream spec.

The Files tab is made up of the following elements (from left to right):

  • Review version selectors: Select which version of the review you want to diff. For details on using the version selectors, see Select review versions to view.
  • File listing header:  
    • Review version and common file path summary:

    • Total number of files: Indicate the number of files that are marked as read out of the total number of files in a review.

    • File change summary icons: Indicate the number of files that have been added, edited, and deleted in this version of the review.
    • Expand the Diff view to full screen: Select the Image of expand diff view to full screen button button to expand the diffs view to full screen. Once the diffs view is expanded to full screen, select the button a second time to exit the full screen mode.

    • Diff actions Image of the Review actions button button: select the Diff actions button to:

      • Expand or collapse all files (expands or collapses all the files within a review if one or more files are in the collapsed or expanded state)

        • Expand all files (only displayed if all or at least one file is collapsed) Select to expand all the files within a review.

        • Collapse all files (only displayed if all files are expanded) Select to collapse all the files within a review.

      • Show or hide all in-line comments for all files in a review (Shows the total number of comments across all files in a review)

        • Hide in-line comments (only displayed if inline comments are expanded): Select to collapse all of the inline file comments.

        • Show in-line comments (only displayed if inline comments are collapsed): Select to expand all of the inline file comments.

      • Show diffs in-line or side-by-side (only works for text files)

        • Show diffs in-line: Select to display the diffs in inline format.

        • Show diffs side-by-side: Select to display the diffs in side-by-side format. The oldest file revision is shown in the left pane, and the newer one is shown in the right pane.

      • Show or hide whitespace and tab characters for all files in a review

        • Show whitespace and tab characters (display of CRLF line endings is only supported in the original Swarm review page): Shows whitespace and tab characters for all text files. The tab characters are padded to show the correct alignment of tabs.

        • Hide whitespace and tab characters: Hides whitespace and tab characters for all text files.

      • Show or hide whitespace diffs

        • Show whitespace diffs: Whitespace changes are highlighted, makes it easier to identify changes in file types where whitespace is important.

        • Hide whitespace diffs: Whitespace changes are not highlighted, this makes it easier to see the important changes in file types where whitespace changes are not important.

      • Navigate to the next file

        Select this option to open the next file in the Diff view or select Alt+N on your keyboard.

      • Navigate to the previous file

        Select this option to open the previous file in the Diff view or select Alt+P on your keyboard.

  • File list:

    Important
    • For a Swarm review containing large number of files, using Ctrl+F to search for a file does not work. You can use the file filter to search for a specific file in the review. To manually select a file from the file stack, scroll through the Review page.

    • By default, when you open the Review page for the first time, the file list panel and the information panel are hidden. Use the Show more context buttons to view the file list panel and the information panel.

      For more information about the show more context buttons, see File diff panel.

    • File filter: Filter by file name, file extension, or folder name to find the files you are interested in. You can see the diff view for the matched search result in the File stack section.
    • File list resize: Change the file list width by dragging the split bar left or right. Alternatively, click the split bar to collapse or expand the file list. If you change the file list width for a review, Swarm saves the width locally for that review. The saved width is used next time you view the review.

    • View complete file list: Use the scroll bar to view the complete list of files.

  • File stack:
    • File change type icons: Each file is marked with a ribbon and an icon indicating whether the file was:
    • File Added/Branched/Imported icon image

      Added/Branched/Imported

      File Edited/Integrated icon image

      Edited/Integrated

      File Deleted icon image

      Deleted

  • File content panel header: The file content panel header contains the following elements from left to right:
  • Image of the Flile content header 

    • File name: The name and revision of the file you are currently viewing.

    • Total number of file comments: The total number of comments for a file. The comments count includes all inline comments and file-level comments. It does not include the archived comments.

    • Show Full Context button (only displayed for text file diffs): Click to toggle between displaying only the portions of the file that have changed and the full file.

    • Open in a new tab button: Click to open the file in a new tab.

    • Mark file as read button: Click to mark the file as read, click again to mark the file as unread.

File diff panel

By default, all files larger than 1 MB in size are truncated. When a file is truncated a message is displayed. Use the max_size configurable in the SWARM_ROOT/data/config.php file to increase or decrease this limit.

  • Text file diff:
  • When you view a diff, the changes are highlighted:

    • Red indicates lines that have been removed.
    • Blue indicates lines that have been modified.
    • Green indicates lines that have been added.

    For more information on the supported extensions for syntax highlighting in the Review page, see Supported syntax highlighting in the Review page.

    Example inline diff view:

    Image of a Swarm review inline diff

    Example side-by-side diff view:

    Image of a Swarm review side-by-side diff

  • Image file diff:

    Image types that are natively supported by your browser are displayed with a vertical slider on the image.

    Drag the slider to the left to reveal more of the newer image and to the right to reveal more of the earlier one. Alternatively, click on the image to move the slider.

    Example image diff:

    Image of an image diff

  • Show more context buttons:

    Sometimes, the concise diff view needs to be expanded to fully understand the context of the change, use the Show More and Show All buttons to display extra lines around the change:

  • Tip

    The following buttons are not available for stream specs.

    • Show the file list panel Show file list pane button (only displayed on the vertical bar next to the file list panel): click to view the file list panel.
    • Show the information panel Show information panel button (only displayed at the bottom of the information panel): click to view the detailed information panel.
    • Show All Lines to Start of File Show All Lines Above button image button (only displayed for the first change in the file): click to show all of the lines up to the start of the file.
    • Show More Lines for the Code Below Show More Lines Above button image button: click to show 10 more lines above the change, the extra lines are displayed in the pane below the button.
    • Show Entire Section Show Entire Section button image button: click to show all of the lines between the changes that are above and below the button, the two changes and the lines between them are displayed in a single pane.
    • Show More Lines for the Code Above Show More Lines Below button image button: click to show 10 more lines below the change, the extra lines are displayed in the pane above the button.
    • Show All Lines to End of File Show All Lines Below button image button (only displayed for the last change in the file): click to show all of the lines down to the end of the file.

Comments tab

The Comments tab is used to view all of the comments in the review.

Image of the Comments tab

Comments are made up of the following elements:

  • Send all notifications (n) (only supported in the original Swarm review page): 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.
  • Comment detail:
    • Commenter avatar and name: The avatar and name of the user that made the comment. Hover over the avatar to see their name and hover over their name to see their ID. Click on the avatar or name to see their user profile. For information about user profiles, see Viewing another user's profile.
    • Review ID: The unique number used to identify the Swarm review.
    • Version link (includes the file and line number if the comment is on a line in a file): Click to go to the review version 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.
    • Filepath link (only if the comment is made on a file): Link to the file the comment is made on, includes line number if the comment was made on line in the file.
    • Comment raised: When the comment was made.
  • 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.
    • No flag displayed: The comment has not been flagged a task. To flag the comment as a task, click the Comment actions Image of the Comment actions button button and select Flag as Open task.
    • Flagged as a Task Image of the Task button 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 Image of the Task Addressed button button: the comment task has been addressed. Click to verify that the task has been addressed correctly, to reopen the task if it has not been addressed correctly, or to verify and archive the task (only supported in the original Swarm review page).
    • Task Verified Image of the Task Verified button 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.
  • Mark comment as read Image of the Mark comment as read button 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 or unread, see Mark comments as read.
  • Restore Restore button image button (archived root level comments only): Click to restore an archived comment. For more information about archiving and restoring comments, see Archiving comments and Restoring comments.
  • Comment actions Image of the Comment actions button button:
    • Flag as Open task: Select flag a comment as a task. For information about working with tasks, see Tasks.
    • Archive: (only available for root level comments): Select to archive a comment and any replies to that comment. For more information about archiving and restoring comments, see Archiving comments and Restoring comments.
  • 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.
  • Comment content: This can be text, a URL, or an attachment (only supported in the original Swarm review page). For more information about the content of comments, see Comment features.
  • Reply Image of the Reply button button: Click to reply to the comment. For information about replying to comments, see Reply to comments.
  • Edit Edit button image button (only available for comments that you have made): Click to edit the comment. For information about editing comments, see Editing comments.
  • Thumbs Up Thumbs Up button button: Click to like a comment. For information about liking comments, see Reacting to comments.

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 Image of the Reply button button and type your comment in the comment text box.

  • Comment text box: type your comment in the text box.
  • Flag as a Task checkbox: Select to flag the comment as a task. For more information about tasks, see Flag a comment as a task.
  • 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 (n) link: Click to post your comment and send the comment notification immediately.
    Where (n) 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.

Activity tab

The Activity tab presents a list of the events on this review.

Review History image

Events in the activity tab 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