Reviews

This section provides information on how to enforce reviews, disable self-approval of reviews by authors, allow author changes, synchronize the description of a review, and expand reviewer group so the group members are displayed individually on the review page.

Review enforcement

Using the enforce trigger script type option, Swarm can optionally require that a change to be submitted is tied to an approved code review, or the submit is rejected. You would most often use this option to ensure that files within specific depot paths have been reviewed.

Additionally, using the strict trigger script type option, Swarm can optionally require that the content of a change to be submitted matches the content of its associated approved code review, or the submit is rejected. Using the strict type implies use of the enforce type. You would most often use this option to prevent users from making changes prior to submitting an already approved review.

These capabilities are provided via the trigger script included with Swarm, but are not enabled by default nor covered in the standard installation steps.

To enable these capabilities, edit the Perforce trigger table by running the p4 triggers command as a user with super-level privileges and add the following lines:

swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport%"
swarm.strict.1  change-content //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"
swarm.strict.2  change-content //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport%"

Note

These trigger table entries assume that the trigger script, swarm-trigger.pl, has been committed to the Helix server within the //.swarm depot. If you have instead copied the trigger script to your Helix server's filesystem (and to the same path on all edge servers in a commit-edge deployment), replace //.swarm/triggers/swarm-trigger.pl with the path to the trigger script.

Customize each line by replacing DEPOT_PATH1 or DEPOT_PATH2 with the appropriate depot path where you wish to enforce review approvals or to apply a strict comparison of review contents.

The above lines include two examples of each of the two new trigger behaviors. Remove unnecessary lines, or add additional lines for specific depot paths as required.

It is also possible to configure exemptions to the enforce and strict verifications, for the number of files in a review or the filetypes in a review. For more information on the trigger's options, see Trigger options.

Group exclusion

You may want to exclude specific users from the enforcement provided by these new trigger lines:

Create a group in the Helix server whose members should be excluded from enforce or strict review restrictions.
Add users who should be excluded to the group.

Note
The owner of a group is not counted as a member of the group, unless the owner's userid is listed as a user in the group.
Edit the trigger table and add -g group_name to each enforce or strict trigger line as desired.

If the group name is review_exclusions, the trigger lines would be similar to:

swarm.enforce.1 change-submit  //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport% -g review_exclusions"
swarm.enforce.2 change-submit  //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t enforce -v %change% -p %serverport% -g review_exclusions"
swarm.strict.1  change-content //DEPOT_PATH1/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport% -g review_exclusions"
swarm.strict.2  change-content //DEPOT_PATH2/... "%//.swarm/triggers/swarm-trigger.pl% -c %//.swarm/triggers/swarm-trigger.conf% -t strict -v %change% -p %serverport% -g review_exclusions"

Disable self-approval of reviews by authors

The Swarm 2015.2 release provides the ability to disable review approval by authors, even if they are moderators or administrators. This is useful for development workflows where review by others is of paramount importance.

To disable review approval by authors, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block:

            'reviews' => array(
                'disable_self_approve' => true,
            ),

The default value is false.

Allow author change

It is possible to allow a user to make themselves the author of a review. This is useful in the case where the original author is no longer available, and someone else needs to take over ownership.

            'reviews' => array(
                'allow_author_change' => true,
            ),

The default value is false. If set to be true, then anyone can claim ownership of a review.

Synchronize review description

By enabling the synchronization of review descriptions, it becomes possible to update the description of a review by updating the description of a changelist associated with the review. Whenever an associated changelist is saved, the text of the review will be updated to match.

Note that attaching another changelist to a review, or updating the files in a changelist will not trigger this update, but updating the description of additional attached changelists will.

            'reviews' => array(
                'sync_descriptions' => false,
            ),

Expand All Limit

The review page has an Expand All button that opens all the files within that review. If the number of files is large, clicking the button might affect performance.

The expand_all_file_limit disables the button if the number of files in the review exceeds the given value. If the value is set to zero, the button is always enabled and can therefore open all the files.

            'reviews' => array(
                'Expand_all_file_limit' => 10,
            ),

The default value if the option is not specified is 10.

Expand group reviewers

By default, reviewer group members are not displayed in the Individuals area of the reviews page when they interact with a review (vote, comment, update, commit, archive, etc.). This avoids overloading the Individuals area with individual avatars if you have large reviewer groups.

Note

An exception to this behavior is when a member of a reviewer group is also an individual required reviewer, in this case their avatar will be displayed in the Individuals area.

When expand_group_reviewers is set to true, reviewer group members are added to the Individuals area of the review page when they interact with the review (vote, comment, update, commit, archive, etc.). If you have large reviewer groups, this might affect performance.

            'reviews' => array(
                'expand_group_reviewers' => false,
            ),

The default value for expand_group_reviewers is false.