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.

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 Named Capturing Groups and Backreferences.

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.

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.

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.

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 version of the review that contains the following files: A^#2, B^#2, C^#3, D^#1, E^#4 (marked for delete), and F^#1

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 version of the review that contains the following files: A^#2, C^#3, E^#4 (marked for delete), and F^#1

Keyword workflow

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

Remove mentions from review descriptions

This example shows how to use regular expressions in the patterns block to remove @mentions in changelist descriptions so they don't get added to the review description.

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( 
            'mentions'  => array(
                'regex' => '/(?P<mention>\s@\S+$|@\S+($|\s))/',
                'spec'  => '%mention%'
            ),
        ),
    ),

Example

Using the above pattern on the following changelist description:

Updated copyright date to 2021.
#review
@bruno
@mei 

If the changelist is shelved, it becomes:

Updated copyright date to 2021.
#review-12345
@bruno
@mei 

The review description would be:

Updated copyright date to 2021.