Review display

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.

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

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 or use the keyboard shortcuts, Shift + Alt + L to view the file list and Shift + Alt + S to view the Information panel.

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

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.

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

Review summary

The Review ID is displayed at the top of the review page. A summary of the review is displayed below the review ID, and contains:

  • 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

The state of the review is displayed in the review description header. 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.

For information about review states, see States.

Vote buttons

The vote buttons are in the review description header. Click a vote button to vote the review up or down. If you have already voted on the review, the vote button you clicked is highlighted. Clicking the button again, clears your vote. If you are not a member of a review, voting on the review adds you as a reviewer.

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 versions to view.

Change state button

The Change state button is also used to change the state of the review. Click to select a new state from the 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.

For information about changing the state of a review, see States.

Review actions button

The Review actions Image of the Review actions button button gives you access to more actions you can perform on the review. Not all of these actions are available to you, the actions available to you depend on your role on the review, the review type, and what is enabled on your Swarm system:

Add change

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.

By default, for a pre-commit or a post-commit review, when a changelist is updated, 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.

The Add change option in the Review actions Image of the Review actions button button is used to add a changelist to an existing review. The option is not available 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.

Tip

You can also add a changelist to a review directly from the changelist description. See Review creation and modification outside of Swarm.

The options available for the Add change option 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 version 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

The Download zip option is available from the Review actions Image of the Review actions button button and is used to download a ZIP archive containing all of the files in the review. The file revisions of the downloaded files are the file revisions in the most recent review version selected in the review version selector. See Select review versions to view.

Note

The Download zip option 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 select the Download zip option, 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.

Change the review author

Note

By default you cannot change the author of a review, this option must be enabled by your Swarm administrator. See Allow author change for details.

If the author of a review is no longer available, or ownership of a review is passed to a different developer, it is useful to be able to change the author of that review.

To change the author of a review:

  1. Click the Review actions Image of the Review actions button button.

  2. Select Change author.

  3. Select the new review author from the user list.

  4. Click Save to change author of the review.

Obliterate a review

Note
  • By default, you must be a user with admin or super user rights to obliterate a review.
  • Optional: Swarm can be configured to allow users to obliterate reviews that they have authored. This can be configured by your Swarm administrator. See Allow author obliterate review.

Obliterate is used to permanently delete reviews that have been created by mistake. For instance, if a review is associated with the wrong changelist, or a review contains sensitive information that should not be openly available.

For information on what happens to a review when it is obliterated, see When you obliterate a review.

Important

Obliterate must be used with care, the review and all of its associated metadata are permanently deleted. An obliterated review cannot be reinstated, not even by Perforce Support.

To obliterate a review:

  1. Navigate to the review.
  2. Click the Review actions Image of the Review actions button button and select Obliterate Review.
  3. Click Yes on the confirmation dialog to complete the obliterate action.
  4. The review is obliterated.

Join or leave a review

The option available depends on whether you are a reviewer on the review or not.

Join a review

  1. Open the review you want to join.

  2. Click the Review actions Image of the Review actions button button.

  3. Select Join review from the dropdown menu. Alternatively, you can Vote Up or Vote Down the review.

  4. Your name is added to the Reviewers list in the Information panel, and you are now a reviewer.

Leave a review

Tip

You cannot leave the review if you are a retained default reviewer on the review or you are a member of a group that is a reviewer on the review

  1. Log in, if you have not already done so.

  2. Open the review you want to leave.

  3. Click the Review actions Image of the Review actions button button.

  4. Select Leave review from the dropdown menu.

    Your name is removed from the Reviewers list in the Information panel, and you are no longer a reviewer.

Mark all comments for the review as read

When you mark a comments as read, the comments are rolled up into single lines to save space. The read flag is remembered independently for each user.

Tip

Mark all comments read will mark all the comments as read including the description comments.

  1. Click the Review actions Image of the Review actions button button.
  2. Select Mark all comments read from the dropdown menu.
  3. All of the comments in the review are rolled up into single lines to save space.
  4. Image of All Comments Marked as Read

Mark all comments for the review as unread

Tip

Mark all comments unread will expand the content of all the comments including the description comments.

  1. Click the Review actions Image of the Review actions button button.
  2. Select Mark all comments unread from the dropdown menu.
  3. The content of all of the comments in the review are expanded.

Refresh projects

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

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.

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.

Review description

The review description is automatically copied from the changelist description when the review is created. 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.

Edit description

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

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

  • If you use Markdown styles in your review description, Swarm renders them when you update the description.

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.

Description comments

You can add comments to the description of the review.

  1. Click Comments (n) (where n is the number of comments that already exist).
  2. Click Add a comment.
  3. Add your comment in the text area.
  4. Click Post.
  5. Tip

    To hide the description comments, click Comments n (where n is the number of description comments that exist). To display the comments again, click Comments n.

To close an empty comment text box, click outside the comment text box or select Esc on your keyboard.

Jobs

A list of jobs that this change fixes, if any.

Adding a job to the review

Swarm does not provide the ability to create new jobs in the Helix Core Server, but jobs can be added to changelists or reviews:

  1. Click Jobs (n) (where n is the number of jobs that are already part of the review).

  2. Click Add a job.

  3. Scroll through the available jobs, or enter job search criteria to search available jobs.

    For more information on job search criteria, see Jobs in Helix Core Command-Line (P4) Guide.

  4. If you find the job you want to add, click it to highlight it and then click Select to add it.

Note

If you attempt to add a job to a review that affects a single project, Swarm applies the project's job view filter to display only jobs that affect the project. It is not currently possible to expand the filter to include jobs outside of the project.

Unlinking a job from the review

Swarm does not provide the ability to delete jobs from the Helix Core Server, but jobs can be unlinked from reviews:

  1. Click Jobs (n) (where n is the number of jobs that are already part of the review).

  2. Click X next to the job you want to unlink.

    The job is immediately unlinked from the review.

Send All Notifications

Comment notifications are delayed by default, click the Send All Notifications (n) link to manually send all of your delayed notifications for the review.

Where n is the number of delayed notifications that will be sent 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 or use the keyboard shortcuts, Shift + Alt + L to view the file list and Shift + Alt + S to view the Information panel.

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

Blocking Approval or Blocking Commit

Shows the total number of items that are blocking approval or commit for a review. Click to see details about the items that are blocking approval for a review. 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.

The Blocking Approval or Blocking Commit list consists of:

  • 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 Individual reviewer 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 Tests.

  • 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

The list of reviewers for the review is displayed in the Information panel to the right of the review description.

The Reviewers list consists of:

  • Edit Edit Description button image button (if enabled): click to edit the reviewers for the review. See Edit reviewers.
  • 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, a vote icon is displayed to the right of the group 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, a vote icon is displayed to the right of the user indicating whether they voted up or down. For more information about individual reviewers, see Individual reviewer.
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 a vote button in the review description header to vote up or down. Your vote is registered for the group, and is also displayed to the right of your name in the Reviewers list. Click on the group in the Information panel to see how individual members have voted on the review.

Changing group vote settings

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

To change the group settings for the review:

  1. Click the Reviewers list Edit Edit Description button image button.

  2. Click the Groups tab.

  3. Click the dropdown arrow to the right of the group you want to change.

  4. Select one of the following for the group:

  5. Optional Default:

    • If any group member votes down the review, an icon is displayed to the right of the group to indicate the group has voted the review down.
    • If at least one group member votes up the review and no members of the group vote down the review, an icon is displayed to the right of the group to indicate the group has voted the review up.

    Require one: Indicated by a star badge with a 1 on the group avatar.

    • If any group member votes down the review, an icon is displayed to the right of the group to indicate the group has voted the review down.
    • If at least one group member votes up the review and no members of the group vote down the review, an icon is displayed to the right of the group to indicate the group has voted the review up. See Required reviewers for details.

    Require all: Indicated by a star badge on the group avatar.

    • If any group member votes down the review, an icon is displayed to the right of the group to indicate the group has voted the review down.
    • If all the group members vote up the review and no members of the group vote down the review, an icon is displayed to the right of the group to indicate the group has voted the review up. See Required reviewers for details.

    Remove from review: Removes the group from the review.

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.

Individual reviewer

When an individual reviewer has voted on a review, a vote icon indicating whether they voted up or down is displayed to the right of their name in the Reviewers list. Required reviewers have a star badge over their avatar.

Changing an individual 's vote settings

You must be the review author, a project member, a project moderator, or a user with super privileges to change settings for an individual reviewer.

To change an individual's settings for the review:

  1. Click the Reviewers list Edit Edit Description button image button.

  2. Click the Users tab if it isn't already displayed.

  3. Click the dropdown arrow to the right of the user you want to change.

  4. Select one of the following for the user:

    • Optional Default

    • Required: Indicated by a star badge over the user's avatar.

    • Remove from review: Removes the user from the review.

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.

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

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

A summary of the number and status of comments flagged as tasks is displayed in the Information panel to the right of the review.

Note

Archived comments that are flagged as tasks are not included in the summary or the Tasks dialog.

Image of Task Counts/Status Summary
  • Red Flag: Displays the number of open tasks on the review.
  • Green check mark: Displays the number of addressed tasks on the review.
  • Blue double-check mark: Displays the number of addressed and verified tasks on the review.

Show Task details Task list button image : Click to display a dialog listing all of the 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 using the buttons at the top of the dialog:

  • 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 change the state of a task from the Tasks dialog, click the task state dropdown for the task and select the new task state.

To view the full comment text for a task, click the ellipses to the right of the task.

Tests

When the review has an associated workflow with tests configured on it or when continuous integration is configured for the project, Swarm 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.

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.

Select review versions to view

Image of the Dropdown Diff Selectors

The review version selectors are used to specify which versions 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.

File list header

The file listing header contains the following elements:

Review version and common file path summary

Total number of read files

Shows the number of files that are marked as read out of the total number of files in a review.

File change summary

The file change icons in the file listing header indicate the number and type of change for the files in the review. For example, the icons below indicate that:

  • One file has been added, branched, or imported

  • Six files have been edited or integrated

  • Zero files have been deleted

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 or use the keyboard shortcut Shift + Alt + F.

Diff actions button

The Diff actions Image of the Diff actions button button gives you access to more actions you can perform when viewing a file diff.

  • Expand or collapse all files in a review

    Expands or collapses all the files within a review if one or more files are in the collapsed or expanded state. Depending on whether the files are expanded or collapsed, use either of the following options:

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

    Use keyboard shortcut Shift + Alt + E to expand or collapse all files in 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. Depending on whether the inline comments are expanded or collapsed, use either of the following options:

    • Hide in-line comments: select to collapse all of the inline file comments.

    • Show in-line comments: select to expand all of the inline file comments.

    Use keyboard shortcut Alt + C to hide or show in-line file comments.

  • Show diffs in-line or side-by-side for a file

    Depending on whether the diffs are shown in-line or side-by-side, use either of the following options:

    • Show diffs in-line: this option only works for text files. Select to display the diffs in inline format.

    • Show diffs side-by-side: this option only works for text files. 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.

    Use keyboard shortcut Alt + L to toggle viewing the diffs in-line or side-by-side for a file.

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

    Depending on whether the diffs are shown with whitespace and tab characters or not, use either of the following options:

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

    Use keyboard shortcut Alt + W to show or hide whitespace and tab characters for all files in a review.

  • Show or hide whitespace diffs for all files in a review

    Depending on whether the diffs are shown with whitespace or not, use either of the following options:

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

    Use keyboard shortcut Alt + D to show or hide whitespace diffs for all files in a review.

  • Navigate to the next file

    Select this option to open the next file in the Diff view or use keyboard shortcut Alt+N.

  • Navigate to the previous file

    Select this option to open the previous file in the Diff view or use keyboard shortcut Alt+P.

  • Show the shortcut help dialog

    Select this option to open the shortcut help dialog to view all the file control keyboard shortcuts or use keyboard shortcut Alt+H.

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 or use the keyboard shortcuts, Shift + Alt + L to view the file list and Shift + Alt + S to view the Information panel.

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

The file list panel contains the following elements:

File filter

Filter files 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

All the files in a review are stacked together to enable you to scroll through each of the files and view their diffs. Select a file to expand the diffs view and select the file a second time to collapse the diff view.

The file stack contains the following elements for each file:

File change type

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

Image of the Flile content header

The file content panel header contains the following elements:

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.

View full context of a file

This button is only displayed for text file diffs. Toggles between displaying only the portions of the file that have changed and the full file.

Open content in a new tab

Click the button to open the selected file in a new browser tab or use keyboard shortcut Alt + T.

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, color is added to the button background and the read by badge is added to the file in the File list.

If a file has been marked as read, click the button a second time to reset the status to unread or use keyboard shortcut Alt + R.

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

For information about working with comments, see Comments.

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