Helix Swarm Guide (2019.1)

Review page quick reference

The Swarm review page is used when reviewing changes:

  1. Log in to Swarm.
  2. To display the Swarm home page, click the Swarm Home Image of the Swarm Home icon icon on the left of the main toolbar.
  3. If your dashboard is not already displayed, click the Dashboard tab.
  4. 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

Image of the Review Description Section

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. The revision of the review being viewed and the total number of revisions available are shown in brackets.
  • 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 Deployment Status Success Icon image or failure Deployment Status Failure Icon image 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 current test status: Tests in Progress Tests in Progress image, Tests Passed Tests Pass Icon image, or Tests Failed Tests Failed Icon image. 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. Clicking on the Tests in Progress Tests in Progress image icon takes you to the details of the previous test result unless it is a new review.
    • 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 Edit Description button image 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.
      • Add Job link image 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 Unlink Job button image button: to unlink a job from the review, click the Unlink Job Unlink Job button image 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 Task list button image 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 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.
  • 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 diff(noun) A set of lines that do not match when two files are compared. A conflict is a pair of unequal diffs between each of two files and a base. (verb) To compare the contents of files or file revisions. See also conflict. 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:
  • Image of Diff Buttons for all Files
    • 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:
  • File change type icons: indicate the type of change for each file in the review:
    • File Added/Branched/Imported icon image Added/Branched/Imported
    • File Edited/Integrated icon image Edited/Integrated
    • File Deleted icon image Deleted

  • File diff view buttons (from left to right): control the diff view for each individual file:
  • Image of Diff Buttons for a Single File
    • Comments in File icon (only displayed if the file contains comments): indicates that the file contains comments.
    • Show In-line button: highlights line additions, modifications, and removals in a single pane.
    • Show Side-by-Side button: highlights additions, modifications, and removals in two panes, with the older version of the file on the left, and the newer version on the right.
    • Show Whitespace button: makes whitespace characters more visible; spaces show up as dots, tabs show up as arrows that point to a bar, and line endings show up as down-pointing arrows.
    • Ignore Whitespace button: toggles the highlighting of whitespace changes in a file, making it easier to identify non-formatting changes. Normally, whitespace is not ignored.
    • Toggle Ignore Whitespace button: toggles the highlighting of whitespace changes in the file diff.
      • 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.
    • Show all diffs button (edited and integrated files only): toggles between displaying all the diffs for the file and only the first few. The limit of what are shown by default is configurable by the administrator (see Max Diffs) and defaults to 1500. If there are fewer than that then this button is hidden.
    • Show Full Context button (edited and integrated files only): toggles between displaying only the portions of the file that have changed and the full file.
    • Open File button (edited or integrated files only): opens a new browser tab/window display the full file (where possible), provide access to its history, and a button to download the file.
    • Mark file as read button (displayed only for code reviews only): helps you (and others) keep track of which files have been reviewed. This is particularly useful when a code review consists of many files.

File diff view

  • Expand file button: click to expand the file to see what has changed, this displays the diff view for the file. Use the File diff view buttons to change how the diff is displayed:
  • 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.

    Example side-by-side diff view:

    Example Diff View image

    Example Diff View image

  • 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:

    • 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.

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 Image of the Mark 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, 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 Image of the Not a Task button button: the comment has not been flagged as a task. Click to flag the comment as a 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 verify and archive the task, or to reopen the task if it has not been addressed correctly.
    • 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.
  • 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 Image of the Like button 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 Image of the Unlike button 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 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 (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.

Review History image

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