Working with reviews in 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 customised 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 since it doesn’t require backing up an external database. For more about using and installing Swarm, please see the Helix Swarm 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.

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

Best practices:

Reviewers:

Request a review from a pending changelist

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

  1. Go to View > Pending changelists, 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.

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

  3. Optionally, select additional options including, 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 P4VS updates the Review ID and the Review State fields with their values from Swarm.

Tip

It is a best practice Add your contentthat you, as the author, keep this pending changelist for subsequent updates to the review. You can use this same changelist to submit the review. If the review is rejected or the review is committed from Swarm, you 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:

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

    Note

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

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

    Every review must have 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 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:

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

  2. In the Add to a Swarm Review dialog, in the Update Review field, enter the review ID of the review to which you’d like to add these files.
  3. Optionally:

Open review in Swarm

If you leave the Open Review in Swarm check box 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, right-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 adds 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 Helix Server server with Swarm integration enabled and do not see the columns, right-click the header row and select these fields.