Working With Reviews in Swarm
Perforce 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 customised to fit into various workflows. Swarm stores all of its metadata including reviews, projects and comments in Perforce, which makes it an attractive solution since it doesn’t require backing up an external database. For more about using and installing Swarm, please see the Swarm User Guide.
Workflow of a review
Below is the happy path workflow for a Swarm review. There are more permutations and variations that are described in the Swarm documentation.
- 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.
- Request a review: For pre-commit code reviews, the Swarm solution uses Perforce shelving technology to get the content to Perforce. For post-commit code reviews, content committed to Perforce is added to a review. In both cases, a Swarm review is created with an id, a description, a set of files and other meta-data including the author, reviewers and comments made on the review.
- Provide review feedback: Reviewers can comment on files or on individual lines of files using Swarm. Reviewers can also add follow-up tasks that the author would be asked to address before the review could be closed.
- Request revisions: If the reviewers find 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.
- Request further review: Authors can request further 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 of their feedback.
- Approve or reject review: Reviews can be approved or rejected using Swarm. Once a review is approved or rejected, it is considered closed.
- Commit the review. For pre-commit reviews, authors can commit reviews using their Perforce clients such as P4V or P4VS. For this scenario, committing a pre-commit code review is synonymous with submitting the changelist associated with the review. They can also optionally use Swarm to commit pre-commit reviews.
Setting up the Swarm integration
A minimum requirement for the P4VS integration is to run Swarm version 2014.4.
None of the new features for Swarm are available unless the Swarm integration is turned on. This integration needs to be turned
on for each Perforce server. In order to make P4VS enable the Swarm features, the Perforce administrator must run the p4 property
command for the Swarm URL. This will tell the Perforce server the Swarm URL. The P4VS integration uses this URL when making
API requests to the Swarm server.
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 the 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_
Authentication with Swarm
P4VS uses the user’s existing Perforce ticket to communicate with Swarm. If you get authorization errors, ensure that the
Use IP-specific tickets when logging in is disabled. This is synonymous with using the -a
option with the p4 login
command so that the ticket can be used on any machine.
Swarm integration features
Once the Swarm integration is enabled a number of new features are available in P4VS including new context menus, review request and update 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.
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 warrant that the author follow on with more submitted changes when wanting to make the 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 View > Pending changelists, select the changelist and choose the Request New Swarm Review… 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 changelists' 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 P4VS 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 that 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 P4VS updates the Review ID and the Review State fields with their values from Swarm.
Update Swarm 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, P4VS provides an option to update an existing Swarm review.
Update a Swarm review from a pending changelist
To update a review from a pending changelist that is associated with the review, go to View > Pending changelists, select the changelist and choose the Update Swarm Review 'xxxx"… 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.
Update a Swarm review from a submitted changelist
To associate a submitted changelist with an existing Swarm review, select the submitted changelist and choose Add to Swarm Review 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 View Review Description button if you want to see a preview of the review’s description in order to verify that this is in fact 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 P4VS launches Swarm to the review page in your default browser. This serves as confirmation that the review has been created or updated.
If a pending or submitted changelist is already associated with a review, context click the changelist and select Open Review 'xxxx' in Swarm… to open the associated review in your default web browser, where xxxx is the id of the associated review.
Review Id and Review State columns
P4VS 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.