Review display

During a code review, reviewers spend most of their time using the review interface.

Review Display Page 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 review interface is very similar to the changelist interface; and provides largely the same functionality, but has several notable differences that are described in the following sections.

Review ID

The Review ID is 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.

Add Change button

Once a review has been started you can add a changelist to the review. It can be useful to add changelists to an existing review. For example, if follow up changes are made to files in a review or if you need to group a number of changelists under a single review.

The Add Change button in the review heading is used to add a changelist to an existing review. The button is not visible if the review is in a state that is protected from change by the review workflow rules. For details of the On update of a review in an end state rule, see Workflow rules.

 

Image of the Add Change button

 

The options available in the Add Change dropdown menu depend on whether the review is pre-commit or post-commit:

  • Pre-commit reviews:
    • Append Pending Changelist: when you add a pending changelist to a review, the files in the changelist are appended to the existing files in the review, see Append a pending changelist to a review.
    • Note

      A review can only contain 1 stream spec. If you append a changelist with a stream spec to a review that already contains a stream spec, the spec in the changelist replaces the original one in the review. If it is a different spec from the original spec in the review, Swarm cannot display the diff between them and displays File content unchanged.

    • Replace with Pending Changelist: when you add a pending changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review, see Replace review with a pending changelist.
    • Replace with Committed Changelist: when you add a committed changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review, see Replace review with a committed changelist.
    • Note

      If you replace a pre-commit review with a committed changelist, the new version of the review will be a post-commit review.

  • Post-commit reviews:
    • Replace with Pending Changelist: when you add a pending changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review, see Replace review with a pending changelist.
    • Note

      If you replace a post-commit review with a pending changelist, the new version of the review will be a pre-commit review.

    • Replace with Committed Changelist: when you add a committed changelist to a review, all of the files in the review are replaced with the files in the changelist you are adding to the review, see Replace review with a committed changelist.
Tip

When the content of a review is changed, Swarm checks to see which branches are in the new revision of the review:

  • If a new branch was added to the review:
    • Default reviewers on the new branch are added to the review.
    • Moderators from the added branch become moderators for the review alongside the existing moderators.
    • Only if workflow is enabled: if the new branch is associated with a workflow, the workflow is merged with the existing workflow. The most restrictive workflow is used for the review.
  • If a branch is no longer part of the review:
    • Reviewers for the review are not changed.
    • Moderators from the removed branch no longer moderate the review.
    • Only if workflow is enabled: if the branch was associated with a workflow, the branch workflow is removed from the review.

Download .zip button

The Download .zip button is used to download a ZIP archive containing all of the files in the review. The version of the files downloaded is the most recent review revision selected in the review revision selector, see Select review revisions to view.

Note

The Download .zip button is not displayed if the zip command-line tool is not installed on the Swarm server. For information about installing, and configuring the zip command-line tool, see Zip archive.

When you click the Download .zip button, Swarm performs the following steps:

  1. Scans the files/folders:
    • Checks that you have permission to access their contents, according to the Helix Core server protections.
    • Checks that the total file size is small enough to be processed by Swarm.
  2. Syncs the file contents to the Swarm server from the Helix Core server.
  3. Creates the ZIP archive by compressing the file content.
  4. Starts a download of the generated ZIP archive.
Note
  • You might not see all of the above steps; Swarm caches the resulting ZIP archives so that repeated requests to the same files/folders can skip the sync and compress steps whenever possible.
  • If an error occurs while scanning, syncing, or compressing, Swarm indicates the error.

Deployment status

When automated deployment has been configured for a project, the deployment success Deployment Status Success Icon image or failure Deployment Status Failure Icon image is indicated in the review's heading. If your deployment program can provide a URL that provides details of the deployment, the indicator becomes linked; click the indicator to see the deployment results.

Test status

When the review has an associated workflow with tests configured on it or when continuous integration is configured for the project, Swarm displays the current test status for the review revision in the review heading:

  • Tests in Progress image Tests in Progress: displayed if any of the tests for the review revision are running.
  • Tests Pass Icon image Tests Passed: displayed if all of the tests for the review revision have passed.
  • Tests Failed Icon image Tests Failed: displayed if any of the tests for the review revision have failed.

To view test run information for tests associated with the review revision, click the Test status to open the dropdown list:

Image of the test status button dropdown list of tests

If your continuous integration system calls back to Swarm with a URL, the test run in the dropdown will be linked to the URL provided.

Review state button

The Review state button displays the current state of the review, and is also used to change the state of the review.

For information on the review states and changing the review state, see States and Change review state.

Edit description

Click the Edit Description icon Edit Description Button image in the review description to update the description to reflect any updates have been made during the review.

Update pending changelist checkbox

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 Update pending changelist checkbox in the Edit Description dialog to also apply your review description changes to the original changelist description.

Tasks

Comments can be flagged as tasks, for more details on working with tasks see Tasks.

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

A summary of the number and status of comments flagged as tasks is displayed below the code review description. Archived comments that are flagged as tasks are not included in the summary.

Image of Task Counts/Status Summary

Click the Task list button Task list button image to display a dialog listing all tasks associated with the review:

Tasks Dialog image

Within the Tasks dialog, you can filter the tasks by the reporter (the userid of the user who created the task), and/or by task state:

  • Click the Red Flag button to display only open tasks (comments that need to be addressed).
  • Click the Green Check Mark button to display only addressed tasks (comments that have been addressed).
  • Click the Blue Double-check Mark button to display only verified tasks (comments that have been addressed and verified).
Note

Archived tasks do not appear in the Tasks dialog.

To view a particular task, select the task in the Tasks dialog, and click the View button. Alternately you can double-click on the task in the Tasks dialog. The Tasks dialog closes and Swarm adjusts the review display so that the chosen task is in view.

Reviewers

A Reviewers area appears below the review's description whenever a review has one or more reviewers, or you are logged in.

Reviewers Area image

This area includes, from left to right, the edit reviewers button Edit Reviewers Button image, the current up and down vote counts, the avatars of current reviewer groups, and the avatars of the current reviewers.

Note

By default, reviewer group members are not displayed in the Individuals area of the reviews page when they interact with a review (vote, comment, update, commit, archive, etc.). This avoids overloading the Individuals area with individual avatars if you have large reviewer groups.

An exception to this behavior is when a member of a reviewer group is also an individual required reviewer, in this case their avatar will be displayed in the Individuals area.

See Expand group reviewers for details on displaying reviewer group members when they interact with a review.

Group reviewer

If you are a member of a group that is a reviewer on the review, click your individual avatar to vote on the review. See the Individual reviewer table for details. Your vote is registered for the group, and is also displayed on your individual avatar. Click on the group avatar to see how individual members have voted on the review:

Group Reviewer Dropdown Menu image

You must be the review author, a project member, a project moderator, or a user with super privileges to change the group settings:

Note

If the review includes content that is part of a project or branch with Retain default reviewers enabled, the following restrictions apply to the review:

  • The voting option for a retained default reviewer can only be changed to a stricter level, you cannot reduce the voting level.
  • Retained default reviewers cannot be removed from the review.
  • Make votes optional:
    • If any group member votes down the review, the group avatar displays a badge indicating that the group has voted down the review.
    • If at least one group member votes up the review and no members of the group vote down the review, the group avatar displays a badge indicating that the group has voted up the review.
  • Make one vote required: Indicated by a star badge with a 1 over the group avatar.
    • If any group member votes down the review, the group avatar displays a badge indicating that the group has voted down the review.
    • If at least one group member votes up the review and no members of the group vote down the review, the group avatar displays a badge indicating that the group has voted up the review. See Required reviewers for details.
  • Make all votes required: Indicated by a star badge over the group avatar.
    • If any group member votes down the review, the group avatar displays a badge indicating that the group has voted down the review.
    • If all the group members vote up the review and no members of the group vote down the review, the group avatar displays a badge indicating that the group has voted up the review. See Required reviewers for details.
  • Withdraw group from review: Removes the group from the review.

Individual reviewer

When an individual reviewer has voted on a review, their avatar displays a badge indicating whether they voted up or down. Required reviewers have a star badge over their avatar.

If you are logged in and viewing a review you did not author, your avatar appears to the right of any other reviewers and its appearance varies according to the following conditions:

Note

If the review includes content that is part of a project or branch with Retain default reviewers enabled, the following restrictions apply to the review:

  • The voting option for a retained default reviewer can only be changed to a stricter level, you cannot reduce the voting level.
  • Retained default reviewers cannot be removed from the review.

When you are not yet a reviewer, or you are a member of a reviewer group who has not yet voted: Clicking your avatar presents a menu allowing you to vote up or down and thereby become an individual reviewer, or simply join the review as an individual reviewer without voting.

When a member of a reviewer group votes they automatically become an individual reviewer as well.

You are not yet a Reviewer, User Avatar Drop-down Menu image

When you are an individual reviewer who has not yet voted: No badge appears on your avatar and clicking your avatar presents a menu allowing you to vote up or down, change whether your individual vote is required or not, or leave the review.

If you are also a member of a reviewer group and you click Leave Review, you will remain a member of the reviewer group.

You are a Reviewer but You have not Voted, User Avatar Drop-down Menu image

When you are an individual reviewer who has voted, or a member of a reviewer group who has voted: Your avatar displays a badge indicating your vote. Clicking your avatar presents a menu allowing you to clear or change your vote, change whether your individual vote is required or not, or leave the review.

If you are also a member of a reviewer group and you click Leave Review, your vote is cleared but you will remain a member of the reviewer group.

You are a Reviewer and You have Voted, User Avatar Drop-down Menu image

When you are a required reviewer, or a member of reviewer group that requires all votes: Your avatar displays a star badge indicating that the review cannot be approved until you vote up. Clicking your avatar presents a menu allowing you to change your vote, make your vote optional, or leave the review.

If you are also a member of a reviewer group and you click Leave Review, you will remain a member of the reviewer group. Make my Vote Optional is not available for members of "all votes required" reviewer groups.

You are a Required Reviewer but You have not Voted, User Avatar Drop-down Menu image

Review approval

A review can be approved when the following requirements are met: 

  • There are no down votes on the review.
  • All of the Required reviewers on the review have voted up.
  • The Minimum up votes on the review has been satisfied for each of the projects and branches the review spans.

Use the Review state button to approve the review.

Tip
  • If the review is moderated, only the moderator can approve the review. For more information about review moderation, see Moderators.
  • Automatic approval of reviews:
    • If the Automatically approve reviews workflow rule is enabled for the review's project/branch, the review is automatically approved as soon as the review requirements are satisfied.
    • If the review has a moderator, the review will not be automatically approved. The moderator must approve the review manually.
  • For more information about the Automatically approve reviews rule, see Workflow rules.

Stale votes

When a review is updated, if the review's list of files, file content, or file-types changes, any votes cast on the review become stale. The vote counts are reset, and the vote indicators become muted.

If you hover your mouse over a reviewer with a stale vote, a tooltip appears displaying the userid, how they voted, and on which version of the review; each version is represented as a point on the Select review revisions to view.

Note

Stale vote handling is not supported for Git-created reviews.

Disable notifications

When you become a review participant, by joining the review or being @mentioned in a comment or in the review's description, you receive notifications for any events associated with the review. If you find that the notifications become more of a burden than benefit and you wish to continue being a review participant, you can disable notifications:

  1. Click your avatar in the reviewers area to display your reviewer options.
  2. Click Disable Notifications.

Once notifications are disabled, you no longer receive notifications. However, if you are @mentioned in a subsequent review comment, you do receive a notification for that comment; regular notifications remain disabled. This approach ensures that you don't miss anything that other reviewers or the review author deems important.

Changing the review author

If the configuration option to allow users to change the author of a review is enabled, then an extra icon is displayed to the left of the Tasks and Reviewers icons. By default this option is disabled, talk to your Swarm Administrator if you require this feature.

Reviewers Area image

If the edit author button Edit Author Button image is displayed, clicking the edit button will open a dialog that allows the author of this review to be changed. This is useful if the original author is no longer available, or ownership has passed to a different developer.

Select review revisions to view

Image of the Dropdown Diff Selectors

The review revision selectors are used to specify which revisions of a review you want to 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., they are located in the Files tab above the list of files.

Tip

If a review consists of one or more Swarm-managed changelists. When comparing versions of a review, Swarm is showing any differences between the selected versions, not the review author's personal changelist. See Internal representation for details.

For information on viewing diffs, see Diffs.

Filter comments button

For involved reviews that have many revisions and many comments, it can sometimes be difficult to determine whether the points expressed in comments have been addressed. To help with such situations, click the Filter comments button Comment Filter Button image to limit the displayed comments to the current review version.

Files tab

The file listing header displays:

Image of a File Listing Heading for a Code Review
  • The current version of the files in the review.
  • Which changelist contains a shelved copy of the review's files.
  • The common path for all of the files in the review.

In diff mode, the file listing header displays:

Image of a File Listing Heading for a Code Review in Diff Mode
  • Which two versions of the review's files are being compared.
  • Which changelists contain the files being compared.
  • The common path for all of the files in both versions of the review.

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

Mark file as read

Beside each file in a review is a Mark file as read button Mark File as Read button image, which help you keep track of which files you have reviewed. The read flag is remembered independently for each user. If the content of a file is changed in an update to the review, the read flag automatically clears. This is particularly useful when a code review consists of many files.

When clicked, the button color inverts and the associated file is visually muted, to make it easy to distinguish read files from unread files:

Image of a File Marked as Read

If a file has been marked as read, click the button a second time to reset the status to unread.

Identifying reviews created with Git Fusion

Git Fusion-initiated reviews include the Git logo beside the main review identifier. This indicator is important because Helix server users cannot update Git Fusion-initiated reviews.

Image of a Review Heading with the Git Logo