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, expand reviewer group so the group members are displayed individually on the review page, and disable tests on approve and commit.
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%"
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.
You may want to exclude specific users from the enforcement provided by these new trigger lines:
Add users who should be excluded to the group.
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.
-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"
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
.
When enabled, Swarm will not allow you to Approve, or Approve and Commit a review that has open tasks. To approve, or approve and commit a review with open tasks, you must address the tasks first and then set them to Task Addressed, or Not a Task, see Set a task to Task Addressed or Not a Task for details.
If the open tasks on the review are archived, the review can then be approved, or approved and committed.
To prevent reviews being approved, or approved and committed when the review has open tasks, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'disable_approve_when_tasks_open' => true,
),
The default value is false
, in this case a warning is displayed for the open tasks but the action is allowed.
By default, when you delete files from a shelved changelist, the files are not removed from the associated review.
When you have a review state set in the process_shelf_delete_when
array, Swarm will automatically carry out the following steps when a file is deleted from a shelf:
process_shelf_delete_when
array. process_shelf_delete_when
array. If process_shelf_delete_when
is configured and the review is in a state that is specified in the array: When the review contains a file that is a common to multiple changelists that are associated with the review, if the owner of any of the associated pending changelists deletes the common file from their shelf, that file will be removed from the review, and a new version of the review will be created. This is true even if the file is not the most recent version in the review.
Required for process_shelf_delete_when
:
You must have the swarm.shelvedel shelve-delete trigger line in the Helix Server trigger table, see Helix Server configuration for Swarm.
To remove files from a review when they have been deleted from an associated shelved changelist and the review is in a specified state, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block. In this example the Needs Review and Needs Revision states are specified:
'reviews' => array(
'process_shelf_delete_when' => array('needsReview', 'needsRevision'),
),
Valid review states for the array:
needsReview
: the review state is Needs Review. needsRevision
: the review state is Needs Revision. rejected
: the review state is Rejected. approved
: the review state is Approved. 'reviews' => array(
'process_shelf_delete_when' => array(),
),
If a review is Approved and Committed or Archived, files will not be removed from the review when they are deleted in an associated shelf. This is true even if the approved:commit
or archived
states are in the process_shelf_delete_when
array.
When enabled, the author of a review can be changed. This is useful in the case where the original author is no longer available, and someone else needs to take over ownership.
To allow the author of a review to be changed, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'allow_author_change' => true,
),
The default value is false
.
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.
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.
To enable synchronize review descriptions, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'sync_descriptions' => true,
),
The default value is false
.
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.
To change the expand all file limit, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'expand_all_file_limit' => 10,
),
The default value if the option is not specified is 10
.
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.
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.
To expand group reviewers, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'expand_group_reviewers' => true,
),
The default value is false
.
When an approved review is committed, disable_tests_on_approve_commit
is used to determine if the automated tests are run on the commit (Automated Tests must be configured). This is a global setting and is used for all of the Swarm projects.
The disable_tests_on_approve_commit
setting is also used when Approve and Commit is selected from Review State dropdown button on the review page.
To disable tests on approve and commit, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'disable_tests_on_approve_commit' => true,
),
disable_tests_on_approve_commit
= false
: automated tests will be run when a review is approved and committed. This is the default setting. disable_tests_on_approve_commit
= true
: automated tests will not be run when a review is approved and committed. This is useful when the tests take a long time and the codeline is stable.The Review display and Changelist display pages have Show More Lines above and Show More Lines Below buttons on the file diff view when a file is expanded. The buttons are used to display more lines of context for the file being viewed. By default 10 extra lines are displayed.
To change the number of lines displayed when the buttons are clicked, update the SWARM_ROOT/data/config.php
file to include the following configuration item within the reviews block:
'reviews' => array(
'more_context_lines' =>15, // defaults to 10 lines
),
The default value if the option is not specified is 10
.