Activities

This section describes the major activities that affect code reviews, including starting a review, updating a review, and fetching a review's files.

Start a review

1. Use the Helix Core command-line (P4) or a client to create the shelved or committed changelist.
2. Start a code review by using one of the following approaches:

Use Swarm:

1. Use Swarm to view a shelved or submitted changelist.
Tip

To view a shelved or submitted changelist, use a Quick URL. For example, if your change is 54321, visit the URL: https://myswarm.url/54321.

2. Click the Request Review button to request a review of that changelist.

Requesting a review on a shelved changelist uses the pre-commit model and requesting a review on a submitted changelist uses the post-commit model.

Use Helix Core command-line (P4):

When you are about to shelve or submit files:

1. Include #review within your changelist (separated from other text with whitespace, or on a separate line).

   Once the review begins, Swarm replaces #review with #review-12345, where 12345 is the review's identifier.

   Note

   The #review keyword is customizable. For details, see Review keyword.

2. At this time, you can add reviewers to the code review by using @mention for users, and @@mention for groups in the changelist description for each desired reviewer.

If your @mention or @@mention includes an asterisk (*) before the userid or groupid, for example @*userid, that user or all of the group members become required reviewers. If your @@mention includes an exclamation mark (!) before the groupid, for example @@!groupid, the members of that group become required reviewers but only one member of the group is required to vote. See Required reviewers for details.

3. Complete your shelve or submit operation.
Warning

If you shelve a changelist and subsequently edit the description to include #review, a review is not started. You must re-shelve the files after adding #review.

Update a review

To update a code review, use one of the following approaches:

• For a pre-commit review that you authored:

  1. Edit the files
  2. Shelve the files

  You can repeat these steps as many times as necessary.

  Tip

  If you want to stop Swarm from updating the review until you have completed your changes, add the work-in-progress tag (#wip by default) to the changelist description. For information on using the work-in-progress tag, see Work-in-progress tag.

• For a post-commit review, or a review where you are not the author:

  1. Fetch the review's files into a new changelist
  2. Edit the files
  3. Update the changelist's description to include #review-12345 (separated from other text with whitespace, or on a separate line)
  4. Shelve the changelist's files

  Once these steps are complete, further updates involve editing the files, and then shelving the changelist's files.

  Warning

  If you use an invalid review identifier, it will appear that nothing happens. Swarm is currently unable to notify you of this situation. If the review has not been correctly updated, use the Add Change button in the Swarm review heading to add the changelist to the review, see Add a changelist to a review.

Fetch a review's files

First, determine the changelist containing the review's files:

1. Visit the review's page.

2. The current review version's changelist appears in the file list heading:

   

   In this example, the changelist is 697707. You use the identified changelist in place of shelved changelist below.

3. Decide whether you will use Helix Core command-line (P4) or P4V to fetch the files, and follow the instructions in the appropriate section below.

Using Helix Core command-line (P4)

1. For a shelved changelist, use a command-line shell and type:

   $ p4 unshelve -s shelved changelist

2. For a committed changelist, use a command-line shell and type:

   $ p4 sync @committed changelist

Using P4V

For a shelved changelist:

1. Select Search > Go To.
2. Change the select box to Pending Changelist.
3. Type in the shelved changelist number and click OK.
4. Select the files in the Shelved Files area.
5. Right-click and select Unshelve.
6. Click Unshelve.

For a committed changelist:

1. Select Search > Go To.
2. Change the select box to Submitted Changelist.
3. Type in the submitted changelist number and click OK.
4. Select the files in the Files area.
5. Right-click and select Get this Revision.
6. Click Close.

Deleting shelves

If you have a number of unused shelves, you can delete them if you want to tidy up your workspace.

To delete a shelf from a changelist without removing the shelved files from the associated review, use Helix Core command-line (P4) or P4V to delete the entire shelf in one operation as described below. This enables you to delete a shelved changelist in your workspace without affecting the associated Swarm review even if Swarm is configured to remove files from a review when they are deleted from a shelf.

Using Helix Core command-line (P4)

To delete a shelved changelist without removing the files from the associated review:

1. Use a command-line shell and type:

$ p4 shelve -d -c changelist

Important

Do not delete the files from the shelf individually. Deleting the entire shelf ensures that files are not removed from an associated review even if Swarm is configured to do so.

2. The shelved files are deleted from the pending changelist.

Using P4V

To delete a shelved changelist without removing the files from the associated review:

1. In P4V, right-click on the pending changelist.
2. Select Delete Shelved Files.
Important

Do not delete the files from the shelf individually. Deleting the entire shelf ensures that files are not removed from an associated review even if Swarm is configured to do so.

3. The shelved files are deleted from the pending changelist.

Edit reviewers

A review author can edit the reviewers for a review by using the Reviewers Edit button in the review page Information panel. Reviewers are able to join or leave reviews, or to change whether their vote is required or optional.

Additionally, the following individuals can edit reviewers:

• Users with admin or super privileges.
• If the review is moderated, the moderators.
• If the review is part of a project, but not moderated, all project members.
• If the review is not part of a project, any authenticated user.

To edit reviewers on a review:

1. Go to the review.

2. From the review Information panel, click the Reviewers list Edit button.

The Manage reviewers dialog is displayed.

3. Click the Users tab to edit a user or the Groups tab edit a group. This field auto-suggests users, and groups within Helix Core Server

   as you type (up to a combined limit of 25 entries).

4. Change the voting requirements of a user or group:

   1. Click the dropdown arrow to the right of the user or group you want to change.

   2. Select one of the following:

• Users: select whether their vote is Required or Optional. A solid star means that their vote is required to approve a review, whereas the outlined star means that their vote is optional.
• Groups: select whether the group vote is Require all, Require one, or Optional. A solid star means that all group member votes are required to approve a review, a solid star with a 1 inside means at least one group member must vote up and no group members vote down to approve a review, and the outlined star means that the group vote is optional.

5. Add a user or group to a review:

   1. Click the Add user or Add group dropdown icon to display a list of users or groups:

   2. Start typing the user or group name, the list is filtered as you type.

   3. Click on the user or group to add to the review.

   4. Click + to add them as a reviewer.

   5. Set the reviewer type from the dropdown to the right of the user or group.

6. Remove a user or group from a review:

   1. Click the dropdown icon to the right of the user or group to be removed.

   2. Select Remove from the review from the dropdown menu.

7. To close the Manage reviewers dialog, click X.