Swarm Integration Features
Once the Swarm integration is enabled a number of new features are available in P4V including new context menus, request review and update review dialogs, badging on pending and committed changes, as well as Review ID and Review State columns.
Request a review
Reviews can be requested 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 since 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.
Request a review from a pending changelist
To request a review from a pending changelist, go to the pending changelist tab, select the changelist and choose from the context menu. Note that 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. The review must have a description, which defaults to the changelist's description. The dialog offers additional options including: reviewers, reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.
Once the review has been requested, the pending changelist is badged with a Swarm icon and P4V updates the review id and the review state fields with their values from Swarm.
 |
It is a best practice for the author to keep this pending changelist for subsequent updates to the review. This same changelist can be used by the author to submit the review. If the review is rejected or the review is committed from Swarm, then the author should manually discard this pending change so that it does not get accidentally committed.
Request a review from a submitted changelist
To request a review from a submitted changelist, go to the Submitted changelist tab, select the changelist and choose the Request New Swarm Review... option from the context menu. Note that 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. The review must have a description, which defaults to the changelists' description. The dialog offers additional options including: reviewers and opening the review in Swarm.
Once the review has been requested, the pending changelist is badged with a Swarm icon and P4V updates the review id and the 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 provides an option to update an existing Swarm review.
Update a Swarm review from a pending changelist
Option 1: From associated pending changelist
To update a review from a pending changelist that is associated with
the review, go to the pending changelist tab, select the changelist
and choose the option from the
context menu, 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. You can also update the review description at this time. The dialog offers additional options including: reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.
Option 2: From a pending changelist not associated to the review
To update a review from a pending changelist that's not yet associated with the review, go to the pending changelist tab, select the changelist and choose the option from the context menu. This scenario is typical if you are working on a different machine than where you originally requested the review or if you've 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. This time the dialog has a field where you can enter the review id of the review you'd like to update with these files. Type in the review id in the Update Review field and click the button if you want to see a preview of the review's description in order to validate this is in fact the review you'd like to update. The dialog offers additional options including: reverting checked out files after they are shelved, not shelving unchanged files, and opening the review in Swarm.
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, select the submitted changelist and choose context menu option.
The Add to a Swarm Review dialog displays a list of files to be added to a review. The dialog has a field where you can enter the review id of the review to which you'd like to add these files. Type in the review id in the Update Review field and click the button if you want to see a preview of the review's description in order to verify that this is the review you'd like to add these files to. The dialog offers an additional options to open the review in Swarm.
Open review in Swarm
If you leave the Open Review in Swarm checkbox option selected in the Review Request or Review Update dialogs, then 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 Perforce which contains these files. The simplest way to get these files from P4V is to use the Go To Spec dialog.
In P4V, open the Go To Spec dialog with the keyboard shortcut of Ctrl+G (⌘+G on Mac)
Type in the review id into the Go To Spec dialog.
P4V displays the Pending Changelist dialog. Select the files you want to unshelve and choose from the context menu.
P4V will display the Unshelve dialog. Choose the pending changelist where you want these files to be unshelved to and click the button. P4V will retrieve a local copy of these files into your workspace.
Review Id and Review State columns
P4V will add a Review Id and Review State column to both the submitted and pending changelist tabs for connections that have the Swarm integration enabled.
 |
If you are connected to a Perforce server with the Swarm integration enabled and do not see the columns, right click on the header row and select these fields.
