Open topic with navigation

Integration with Swarm

Helix Swarm is a powerful and flexible code review and collaboration solution that helps teams ship quality software faster. Swarm enables review of code and other assets before or after commit and can be customized to fit into various workflows. Swarm stores all of its metadata (including Reviews, Projects, and Comments) in Helix Server, which makes it an attractive solution because it does not require backing up of an external database. For more about using and installing Swarm, see the Helix Swarm Guide.

Review workflow

Following is the happy path workflow for a Swarm review. For more permutations and variations, see the Helix Swarm Guide.

1. Make local changes to files: Swarm reviews can follow either a pre-commit or post-commit workflow. In both models, the author would make some local content changes to one or more files and then get those content changes into Perforce.
2. Request a review: For pre-commit code reviews, the Swarm solution uses Helix Server shelving technology to get the content to Helix Server. For post-commit code reviews, content committed to Helix Server is added to a review. In both cases, a Swarm review is created with an ID, a description, a set of files, and other metadata, including the author, reviewers, and comments made on the review.
3. Provide review feedback: Reviewers can comment on files or individual lines in files using Swarm. They can also add follow-up tasks that the author should address before the review can be closed.
4. Request revisions: If the reviewers find that the review needs more work, which is often the case, they can change the state of a review to Needs Revision, thereby notifying the author that the review is back in their court.
5. Request further review: Authors can request another round of review of their review content changes and update any of the tasks they were asked to complete, thereby notifying the reviewers that they are ready for more feedback.
6. Approve or reject review: Reviewers can approve or reject a review using Swarm. When they approve or reject a review, the review is considered closed.
7. Commit the review: For pre-commit reviews, authors can commit reviews either using Swarm or their Helix Server clients, such as P4V or P4VS. For the latter scenario, committing a pre-commit code review is synonymous with submitting the changelist associated with the review.

Setting up the Swarm integration

To use the full list of features of the P4V integration with Swarm, you need to have Swarm 2014.4 or later installed. The P4V integration also works with Swarm 2014.3, but some features, such as the required reviewers option, are not visible. For details on how to set up the Swarm integration, see Configuring Swarm connections in the Helix Core Server Administrator Guide: Fundamentals.

Example p4 property command to run:

p4 property -a -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

where https://swarm.yourcompanydomain.com is the URL for your Swarm server.

If you are testing the Swarm integration, you may wish to set the property for a specific user. For example, to enable the Swarm integration for the user username:

p4 property -a -u username -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

Similarly, you can enable the Swarm integration for a specific group of users. For example, to enable the Swarm integration for the group group:

p4 property -a -g group -n P4.Swarm.URL -v https://swarm.yourcompanydomain.com

p4 property -a -n P4.Swarm.Timeout -v 10

Swarm integration features

When Swarm integration is enabled, a number of additional features is available in P4V, including new context menus, request review and update review dialogs, badging on pending changes, committed changes, and history, as well as Review ID and Review State columns.

Request a review

You can request reviews from either pending or submitted changelists. Note that a changelist cannot be associated with more than one review. However, a review can have more than one changelist associated with it.

Best practices:

• Pre-commit code reviews are a more popular approach because they allow validating of code and correcting defects before they become a part of the committed code base. Swarm supports pre-commit code reviews via pending changelists.
• Post-commit code reviews allow reviewers to provide feedback on the submitted content, and they allow the author to follow on with more submitted changes when making updates recommended by the reviewers. Development branches are well-suited for the post-commit review process.

Reviewers:

• When you select reviewers, you can make them required or optional.
• When you select a group as reviewer, you can make all members optional, all members required, or decide that only one member of the group is required to review.
• If a user is specified as an optional reviewer, but the same user is also the member of a group of which all members are required to review, then this user is actually a required reviewer.

Request a review from a pending changelist

To request a review from a pending changelist, do the following:

1. Go to the pending changelist tab, right-click the changelist, and select Request New Swarm Review​.

   Note

   If the changelist is already part of a Swarm review, this option is not available.

   

   The Request New Swarm Review dialog displays a list of files to be shelved in order to request the review. If the changelist already has shelved files, the dialog also lists these already shelved files. The aggregate of the shelved files comprises the review.

2. In the Request New Swarm Review dialog, enter a description.

   Each review requires a description. The default description is the changelist's description.

3. Optionally, select additional options, including: reviewers (users or groups), reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.

   

4. Click Request Review.

   The pending changelist is badged with a Swarm icon, and P4V updates the Review Id and Review State fields with their values from Swarm.

   

Request a review from a submitted changelist

To request a review from a submitted changelist, to the folloing:

1. Go to the Submitted changelist tab, right-click the changelist, and select Request New Swarm Review.

   Note

   If the changelist is already part of a Swarm review, this option is not available.

   

   The Request New Swarm Review dialog displays the files to be added to the review.

2. In the Request New Swarm Review dialog, enter a description.

   Each review requires a description. The default description is the changelist's description.

3. Optionally, select additional options, including reviewers and opening the review in Swarm.

   

4. Click Request Review.

   The pending changelist is badged with a Swarm icon, and P4V updates the Review Id and Review State fields with their values from Swarm.

   

Update a review

If you need to update the files in a review for any reason, such as to respond to the feedback you received from the reviewers, P4V lets you update an existing Swarm review.

Update a Swarm review from a pending changelist

When updating a Swarm review from a pending changelist, the changelist can -- but does not have to be -- already associated with the review.

Option 1: Update from an associated pending changelist

To update a review from a pending changelist that is associated with the review, do the following:

1. On the Pending tab, right-click the changelist and select Update Swarm Review 'xxxx', where xxxx is the review ID.

   

   The Update Files in Review dialog displays a list of files to be shelved in order to update the review. If the changelist already has shelved files, the dialog also lists these already shelved files. The aggregate of the shelved files comprises the updated review.

2. If needed, update the review description.

3. Optionally, select additional options, including reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.

   

4. Click Update Files.

   The files in the associated review are updated.

Option 2: Update from a pending changelist not associated with the review

To update a review from a pending changelist that is not yet associated with the review, do the following:

1. On the Pending tab, right-click the changelist and select Update Swarm Review.

   This scenario is typical if you are working on a different machine than where you originally requested the review or if you have discarded the original changelist you used for creating the review. If you already have a changelist associated with the review, you would likely use that changelist and follow the instructions in option 1.

   

   The Update Files in Review dialog displays a list of files to be shelved in order to update the review.

2. In the Update Review field, enter the ID of the review you would like to update with these files.

   
3. Optionally, to validate if this review is in fact the review you would like to update, click View Review Description.
4. Optionally, select additional options, including reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.

5. Click Update Review.

   The changelist you used to update the review becomes associated with the review.

Update a Swarm review from a submitted changelist

To associate a submitted changelist with an existing Swarm review, do the following:

1. Right-click the submitted changelist and select Add to Swarm Review.

   

   The Add to a Swarm Review dialog displays a list of files to be added to the review.

2. In the Update Review field, enter the ID of the review to which you would like to add these files.

   
3. Optionally, to validate if this review is in fact the review to which you would like to add these files, click View Review Description.
4. Optionally, select additional options.

5. Click Add to Review.

   The files get added to the review.

Open a review in Swarm

If you leave the Open Review in Swarm check box option selected in the Review Request or Review Update dialogs, P4V launches Swarm to the review page in your default browser. This serves as confirmation that the review has been created or updated.

Getting Files from a Review

As a reviewer, you may be inspecting a review in Swarm and decide you need to get a local copy of the files. The review ID shown in Swarm corresponds to a pending changelist in Helix Server that contains these files. The simplest way to get these files from P4V is to use the Go To Spec dialog, as follows:

1. In P4V, open the Go To Spec dialog with the keyboard shortcut of +G (+G on Mac).

   

2. Enter the review ID and click OK.

   P4V displays the Pending Changelist dialog.

3. Right-click the files you want to unshelve and select Unshelve.

   

   P4V displays the Unshelve dialog.

   

4. Select the pending changelist to which you want these files to be unshelved and click Unshelve.

   P4V retrieves a local copy of these files into your workspace.

Review ID and Review State columns

P4V adds a Review Id and Review State column to the Submitted and Pending tabs and the History tab for connections that have the Swarm integration enabled.

If you are connected to a Helix Server with the Swarm integration enabled and do not see the columns, right-click the header row and select these fields.

Reconnect to Swarm

If the connection to Swarm is interrupted, you can re-establish it from the Connection > Reconnect to Swarm menu.