Review keyword

This section describes how to configure keywords, and how to use keywords in a changelist description to create a review, and add a changelist to a review.

Review keyword configuration

The keyword can be configured with a regular expression so that most any keyword syntax can be used. If you choose to customize the review keyword, take care to choose syntax and terminology that is unlikely to occur in a changelist description, to avoid unexpected Swarm activity.

To configure the review keyword, add the following block to the SWARM_ROOT/data/config.php file:

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'patterns' => array( 
            'octothorpe' => array(     // #review or #review-1234 with surrounding whitespace/eol
                'regex'  => '/(?P<pre>(?:\s|^)\(?)\#(?P<keyword>review|append|replace)(?:-(?P<id>[0-9]+))?(?P<post>[.,!?:;)]*(?=\s|$))/i',
                'spec'   => '%pre%#%keyword%-%id%%post%',
                'insert' => "%description%\n\n#review-%id%",
                'strip'  => '/^\s*\#(review|append|replace)(-[0-9]+)?(\s+|$)|(\s+|^)\#(review|append|replace)(-[0-9]+)?\s*$/i',
            ),
            
            'leading-square' => array(     // [review] or [review-1234] at start
                'regex'  => '/^(?P<pre>\s*)\[(?P<keyword>review|append|replace)(?:-(?P<id>[0-9]+))?\](?P<post>\s*)/i',
                'spec'  => '%pre%[%keyword%-%id%]%post%',
            ),

            'trailing-square' => array(     // [review] or [review-1234] at end
                'regex'  => '/(?P<pre>\s*)\[(?P<keyword>review|append|replace)(?:-(?P<id>[0-9]+))?\](?P<post>\s*)?$/i',
                'spec'   => '%pre%[%keyword%-%id%]%post%',
            ),
        ),
    ),

Multiple patterns can be specified; the first successful match is used and none of the other patterns are evaluated.

The keyword types are grouped under their identifiers. In each group, the regex item specifies the regular expression to be used to identify the review keyword in the changelist description. The spec item is used when the review keyword needs to be updated.

Note

The use of named capture groups in the regex, for example (?<pre>\s*). The values captured during regex matching are used to replace any identically named placeholder values in the spec item that are surrounded by percent % characters. In the example configuration above, the pre and post capture groups and placeholders maintain any whitespace surrounding the review keyword.

For octothorpe (or "hashtag") review keywords, these can appear anywhere in the changelist description. The strip item is used to ensure that the keyword is removed from the review description if it appears at the start or end of the changelist description. The insert item is currently not used; it is included here to prevent future upgrade issues. The intended use case is when a review is started and the changelist does not already contain a review keyword, the insert item would be used to add the review keyword to the changelist description.

For more information on named capture groups in PHP, see: http://www.regular-expressions.info/named.html

Create a review

By default, including the keyword #review within a changelist description (separated from other text with whitespace, or on a separate line) tells Swarm that a review should begin when the changelist is shelved or committed.

Once a review has begun, Swarm adds the review identifier to the #review keyword, for example #review-1234. This tells Swarm which review should be updated whenever the original changelist is re-shelved or committed.

Note

If you create a pre-commit review and a user appends a changelist to your review, the default add mode of your review is changed from replace to append, see Add a changelist to a review for details.
Swarm acts on the first valid keyword it finds in the changelist description, Swarm then ignores any further valid keywords it finds in the description.
Swarm can also accept [review] at the start or end of the changelist description, but this form of review keyword is now deprecated and is likely to be removed in a future version of Swarm.

Add a changelist to a review

Once a review has been started you can add a changelist to the review. It can be useful to add changelists to an existing review. For example, if follow up changes are made to files in a review or if you need to group a number of changelists under a single review.

Note

The changelist must not be part of another review, if it is Swarm will reject it.

Note

Swarm acts on the first valid keyword it finds in the changelist description, Swarm then ignores any further valid keywords it finds in the description.

By default, the #append-, #replace-, and #review- keywords along with the review identifier (separated from other text with whitespace, or on a separate line) can be used in a changelist description to add changelists to an existing review. The options available depend on whether the review is pre-commit or post-commit:

Pre-commit reviews:
- #append- + review identifier. When you add a changelist to a review with the append option, the files in the changelist are appended to the existing files in the review. This changes the default add mode of the review to append.
- #replace- + review identifier. When you add a changelist to a review with the replace option, all of the files in the review are replaced with the files in the changelist you are adding to the review. This changes the default add mode of the review to replace.
- Note
  If you replace a pre-commit review with a committed changelist, the new version of the review will be a post-commit review.
- #review- + review identifier. When you add a changelist to a review with this option, the review's default add method is used. The default add method can be either replace or append and it is set by the most recent add method used on the review:
  - When a review is first created the default add mode for the review is replace.
  - If a changelist is added to the review using append, the default add mode for the review is set to append.
  - If a changelist is added to the review using replace, the default add mode for the review is set to replace.
  - If you do not know what the current default add mode of the review is, delete the #review- keyword and specify the add mode you want by using either #append- + review identifier, or #replace- + review identifier.
Post-commit reviews:
- #review- or #replace- + review identifier. When you add a changelist to a review with the replace changelist option, all of the files in the review are replaced with the files in the changelist you are adding to the review.
- Note
  If you replace a post-commit review with a pending changelist, the new version of the review will be a pre-commit review.

Tip

When the content of a review is changed, Swarm checks to see which branches are in the new revision of the review:

If a new branch was added to the review:
- Default reviewers on the new branch are added to the review.
- Moderators from the added branch become moderators for the review alongside the existing moderators.
- Only if workflow is enabled: if the new branch is associated with a workflow, the workflow is merged with the existing workflow. The most restrictive workflow is used for the review.
If a branch is no longer part of the review:
- Reviewers for the review are not changed.
- Moderators from the removed branch no longer moderate the review.
- Only if workflow is enabled: if the branch was associated with a workflow, the branch workflow is removed from the review.

Example: Appending a changelist to review 1234:

Add #append-1234 to the changelist description.

Original review contains the following files: A^#1, B^#2, C^#1, D^#1, and E^#4
Changelist contains the following files: A^#2, C^#3, E^#4 (marked for delete), and F^#1
Appending the changelist to the original review generates a new revision of the review that contains the following files: A^#2, B^#2, C^#3, D^#1, E^#4 (marked for delete), and F^#1

Important

Committing a review with Swarm (recommended): Swarm automatically commits the files in the approved revision of the review.

Committing a review outside of Swarm:

Before you commit the review:

Unshelve the review into the pending changelist associated with the review.
Reshelve the files in the pending changelist.
Commit the pending changelist.
This process ensures that all of the files in the approved revision of the review are committed.

Workflow technology preview feature disabled (default):

Swarm can be configured to automatically check that the files being committed match the files in the approved revision of the review, see the strict trigger option.

Workflow technology preview feature enabled:

Swarm can be configured to automatically check that the files being committed match the files in the approved revision of the review by using the On commit with a review workflow rule. For information about the On commit with a review rule, see Workflow rules.

Example: Replacing the files in a review 1234 with the files in a changelist:

Add #replace-1234 to the changelist description.

Original review contains the following files: A^#1, B^#2, C^#1, D^#1, and E^#4
Changelist contains the following files: A^#2, C^#3, E^#4 (marked for delete), and F^#1
Replacing the original review with the changelist generates a new revision of the review that contains the following files: A^#2, C^#3, E^#4 (marked for delete), and F^#1

Tip

When you replace a review with a changelist, the base versions of the files in the new revision of the review are the base versions of the files in the replacement changelist.

Keyword workflow

For workflow examples using keywords, see Review creation, and modification outside of Swarm.