Reviews

This section describes the configurables that can be set for reviews.

Tip

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

Allow author change

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:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'allow_author_change' => true,
    ),

The default value is false.

Allow author obliterate review

When enabled, users can obliterate reviews that they have authored. For details about how to obliterate a review, see Obliterate Review.

Important

By default, only users with admin and super user rights can obliterate a review. Perforce recommends that the allow_author_obliterate configurable is kept at its default value of false. An obliterated review cannot be reinstated, not even by Perforce Support.

To allow users to obliterate reviews that they have authored, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'allow_author_obliterate' => true,
    ),

The default value is false.

Disable approve for reviews with open tasks

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.

Important

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:

<?php
    // this block should be a peer of 'p4'
    '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.

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:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'disable_self_approve' => true,
    ),

The default value is false.

Disable tests on approve and commit

Important

From Swarm 2020.1, the disable_tests_on_approve_commit configurable has been removed from Swarm. This functionality has been moved to workflows and is set on a per workflow per test basis. A test can be set to run On Update or On Submit for a specific workflow or globally by setting the test on the global workflow.
If the disable_tests_on_approve_commit configurable is in your swarm_root/data/config.php file, it is ignored.

Protected end states

By default, the content of a review can be updated no matter what state the review is in. Reviews can be protected from automatic content change if they are in a specified state by using the end_states configurable.

Tip

When a review is in a protected end state, it can still be updated manually by a user from the Swarm UI.

Workflow:

If workflow is enabled (default): the end_states configurable sets the protected review states. A combination of the On update of a review in an end state rule and workflows determines which projects and branches have protected reviews.
If workflow is disabled:: when the content of a review is updated, the end_states array is checked to see if the review can be updated. If the review state matches a state in the end_states array the submit is rejected.

To set the protected review states, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block. In this example the Archived, Rejected, and Approved : Committed states are specified:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'end_states' => array('archived','rejected', 'approved:commit'),
    ),

Valid review states for the array:

archived: the review state is Archived.
rejected: the review state is Rejected.
approved:commit: the review has been approved and committed, the review state is Approved : Commit.
approved: the review state is Approved.

By default the array is empty, review content can be updated no matter what state the review is in.

Expand all file 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.

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:

<?php
    // this block should be a peer of 'p4'
    '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.

To expand group reviewers, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'expand_group_reviewers' => true,
    ),

The default value is false.

Maximum initial reviewers and reviewer groups in secondary navigation bar

By default, a maximum of 6 individual reviewers and 6 reviewer groups are initially displayed in the secondary navigation pane on the Review page. If there are more individual reviewers or reviewer groups on the review, the + n more link is displayed as required so that you can display all of the reviewers and reviewer groups.

For example, with the default value of 6:

8 individual reviewers on the review: 6 displayed in the secondary navigation bar and the remainder are available on the + 2 more link
9 reviewer groups on the review: 6 reviewer groups are displayed in the secondary navigation bar and the remainder are available on the + 3 more link

To edit the maximum number of reviewers and reviewer groups initially displayed in the secondary navigation pane, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block. For example, to set the maximum number of reviewers and reviewer groups to 10:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'max_secondary_navigation_items'  => 10, // defaults to 6 reviewers
    ),

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

Moderator behavior when a review spans multiple branches

By default, when a review spans multiple project branches that have different moderators, only one moderator from any one of the branches needs to approve the review. Set the configurable to each to require one moderator from each branch approve the review. If a moderator belongs to more than one of the branches spanned by the review, their approval will count for each of the branches they belong to.

To require one moderator from each branch to approve a review, edit the SWARM_ROOT/data/config.php file and set the moderator_approval configurable to each in the reviews section of the codeblock:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'moderator_approval' => 'each', // 'any|each'
    ),

The default value is any.

More context lines

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:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'more_context_lines' =>15, // defaults to 10 lines
    ),

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

Process shelf file delete when

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:

Check to see if the shelf is associated with a review.
The deleted file is only removed from the review if the review state matches the review state in the process_shelf_delete_when array.

Tip

More than one review state can be specified in the process_shelf_delete_when array.
When files are removed from a review, any votes on the review become stale. The vote counts are reset, and the vote indicators are muted.
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.

Important

Required for process_shelf_delete_when:

A supported version of Helix Core Server (standard maintenance), see Helix Core Server requirements.
You must have the swarm.shelvedel shelve-delete trigger line in the Helix Core Server trigger table, see Installing Triggers.
You must satisfy the Swarm trigger dependencies, see Trigger dependencies.

Important

Do not use the Swarm user that is configured in the Swarm configuration file when deleting shelves, or deleting files from shelves. The Swarm logic processes the shelve-delete trigger event, if the event is invoked by the Swarm user it is rejected. The delete operations will fail.

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:

<?php
    // this block should be a peer of 'p4'
    '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.

Leave the array empty to disable this feature, see below. This is the default setting for the array.

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'process_shelf_delete_when' => array(),
    ),

Note

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.

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

The update is not triggered if:

another changelist is attached to a review.
files are updated in a changelist attached to a review
a user selects Update pending changelist when editing a review description.

To enable synchronize review descriptions, update the SWARM_ROOT/data/config.php file to include the following configuration item within the reviews block:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'sync_descriptions' => true,
    ),

The default value is false.

Review complexity

Review complexity is displayed for each review in the Complexity column on the Reviews list page to help users to quickly see how complicated each review in the list is. By default, review complexity is based on the number of lines changed in the files in a review and simply displayed as high, medium, or low for each review. The values for high and low complexity are set using the high and low configurables.

Tip

Review complexity is only calculated for a review when the review is updated and the file content has changed.
Review complexity is only stored for the current version of a review.
If you change the high or low complexity value, complexity is only recalculated for a review when the review is updated and the file content has changed.

To change the complexity values, update the SWARM_ROOT/data/config.php file with item within the reviews block:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'statistics' => array(
            'complexity' => array(
                'calculation' => 'default', // 'default|disabled'
                'high' => 300,
                'low' => 30
            ),
        ),
    ),

calculation
- default the complexity is based on the number of lines changed in the files in the review. For the purposes of complexity, a new file is counted as the number of lines in the file. Default value is default.
- disabled set to disabled to disable the complexity calculation.
high set the number (integer) of line changes that are considered high for your organization. Default value is 300.
low set the number (integer) of line changes that are considered low for your organization. Default value is 30.

By default, complexity is calculated as:

High: number of lines changed in files in the review ≥ high.
Medium: number of lines changed in files in the review < high and > low.
Low: number of lines changed in files in the review ≤ low.

Maximum files limit

Tip

Do not set max_files configurable to a low number as this will allow commits to bypass workflow and moderators that are blocking approval. It will not bypass review association. A commit must meet the workflow rule of being associated to a review.

When creating or updating a review you can set a maximum file limit. This limits the maximum number of files that can be added to a review. If a request exceeds the maximum file number limit then a review is not created or updated.

To edit the maximum file limit, update the max_files configurable under the reviews section in the SWARM_ROOT/data/config.php file.

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'max_files' => 25,
    ),

By default, max_files configurable is set to 0.

Automatically resolve outdated files

When committing changes for a review that contains outdated files, you must first update the review or all the shelved files to ensure that every file in the changelist is current. Ensure that the review linked to the changelist is also updated. If a changelist contains files that must be resolved then Swarm will attempt to auto-resolve the files if there are no merge conflicts.

To enable auto-resolve for files in a changelist, update the auto_resolve configurable under the reviews section in the SWARM_ROOT/data/config.php file.

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'auto_resolve' => true,
    ),

By default, auto_resolve configurable is set to false.