Introduction

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 of an external database. For more about using and installing Swarm, please see the Swarm documentation.

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 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 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.

  3. 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.

  4. 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.

  5. 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.

  6. Approve or reject review: Reviews can be approved or rejected using Swarm. Once a review is approved or rejected, it is considered closed.

  7. 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 P4V integration is to run Swarm version 2014.4. The P4V integration will only work with Swarm version 2014.3 or higher. With Swarm 2014.3, the P4V integration cannot show the required reviewers option when selecting users to be reviewers, whereas, with Swarm 2014.4 or later the P4V integration shows the required reviewer option.

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 P4V enable the Swarm features, the Perforce administrator must run the p4 property command for the Swarm URL. This tells the Perforce server the Swarm URL. The P4V 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 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

Note

P4V uses a Swarm integration timeout to limit delays in the P4V user interface. The timeout can be adjusted with: 

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

The timeout is measured in seconds, and the default is 10 seconds. The timeout can be set for a specific user or a specific group by including the -u username or -g group options, respectively.

Authentication with Swarm

P4V 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.