Activities // Swarm 2014.1: User Guide

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

To start a code review, choose one of the following approaches:

When you use Swarm to view a submitted changelist, click the Request Review button to request a review of that changelist. This uses the post-commit model.
When you use Swarm to view a shelved changelist, click the Request Review button to request a review of that shelved changelist. This uses the pre-commit model.
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 an @mention in the changelist description for each desired reviewer.
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.
When you are using Git Fusion, you can start a review by pushing your changes to a target branch using the following command:
```
$ git push origin review/master/new
```
master is the target branch that the proposed changes are intended for.

Important

The target branch must be mapped to a named Perforce branch in the Git Fusion repo configuration.

See "Setting up Repos" in the Git Fusion Guide for details on converting a lightweight branch into a fully populated Perforce branch.

When the command completes, the output indicates the review id that has been created:
```
remote: Perforce: Swarm review assigned: review/master/1234
```
where 1234 is the review id that was just created.

Tip

For more information on Git Fusion, see the Git Fusion Guide

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. if the changelist does not already contain #review-12345, where 12345 is the review's identifier, update the changelist description to include #review-12345 (separated from other text with whitespace, or on a separate line)
3. shelve the files
You can repeat these steps as many times as necessary.

Warning!

If you use an invalid review identifier, it will appear that nothing happens. Swarm is currently unable to notify you of this situation.
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, you can repeat steps 2-4 using the same changelist for any further updates.

Warning!

If you use an invalid review identifier, it will appear that nothing happens. Swarm is currently unable to notify you of this situation.
When you are working with Git Fusion:

Important

You can only update Git Fusion-initiated reviews using Git Fusion.

In the following example, the target branch is master, the review id is 1234, the Git Fusion hostname is gfserver, and the remote repo name is p4gf_repo.
1. Fetch the review's head version:
```
$ git fetch --prune origin
From gfserver:p4gf_repo
 * [new_branch]      review/master/1234 -> origin/review/master/1234
 x [deleted]         (none)     -> origin/review/dev/new
```
  The --prune option lets the local Git repo delete the unwanted review/master/new reference created by the initial git push origin review/master/new command.
2. Check out the review's head version:
```
$ git checkout review/master/1234
```
3. Edit the files as required.
4. Add the edited files to the index of files, in preparation for the next commit.
  
  There are several ways to do this. For example, to add all modified files to the index, run:
```
$ git add -A
```
5. Commit the files in Git:
```
$ git commit -m "made some changes"
```
6. Push the Git changes to the review:
```
$ git push origin review/master/1234
```
  Note
  
  If you get review feedback that is better expressed as a Git rebase and cleaned up history, you can make your changes and push them as a new review.
  
  You cannot clean up history and then push your changes to the same review.
Tip

For more information on Git Fusion, see the Git Fusion Guide

Fetch a review's files

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

Visit the review's page.
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.
Decide whether you will use p4, P4V, or Git Fusion to fetch the files, and follow the instructions in the appropriate section below.

Using P4

For a shelved changelist, use a command-line shell and type:
```
$ p4 unshelve -c shelved changelist
```
For a committed changelist, use a command-line shell and type:
```
$ p4 sync @committed changelist
```

Note

Your client's view mappings need to include the changelist's path.

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. Context-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. Context-click, and select Get this Revision.
6. Click Close.

Using Git Fusion

In the following example, the target branch is master, the review id is 1234, the Git Fusion hostname is gfserver, and the remote repo name is p4gf_repo.

Fetch the review's head version:

$ git fetch --prune origin
From gfserver:p4gf_repo
 * [new_branch]      review/master/1234 -> origin/review/master/1234
 x [deleted]         (none)     -> origin/review/dev/new

The --prune option lets the local Git repo delete the unwanted review/master/new reference created by the initial git push origin review/master/new command.

Check out the review's head version:
```
$ git checkout review/master/1234
```

Important

You can only update Git Fusion-initiated reviews using Git Fusion.

Tip

For more information on Git Fusion, see the Git Fusion Guide