Review display

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

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.

Refresh projects button

When a review is created or updated, Swarm checks to see what projects the review files are associated with and links the review to the projects it finds. If at a later date a new project is created or a new branch is added to a project, Swarm does not check to see if existing reviews are associated with new projects or project branches.

The Refresh projects button is used 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.

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.

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.

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.

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.

Deployment status

When automated deployment has been configured for a project, the deployment success or failure 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: displayed if any of the tests for the review revision are running or if any On Demand tests have not been run.
• Tests Passed: displayed if all of the tests for the review revision have passed.
• 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 Test status to open the dropdown list:

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.

The following actions are available from the dropdown list of tests for tests called by a workflow:

• Rerun test: if a test has completed you can rerun the test, click 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 to manually run the test for the most recent version of the review.

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

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.

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

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

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.

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

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:

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

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

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.

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.

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.

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.

Review approval

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

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

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.

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.

If the edit author button 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

The review revision selectors are used to specify which revisions of a review you want to diff(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.

• Left dropdown selector: the base version for the review is selected by default, base is the version of the file that was checked out of the depot before it was changed for this review. The current version in the depot, sometimes called HeadThe most recent revision of a file within the depot. Because file revisions are numbered sequentially, this revision is the highest-numbered revision of that file. can be selected, if there are multiple revisions of the review a specific revision can be selected.
• Right dropdown selector: the latest revision of the review is selected by default. If there are multiple revisions of the review, a specific revisions of the review can be selected.

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 to limit the displayed comments to the current review version.

Files tab

The file listing header displays:

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

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

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

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.