Swarm 2017.2 Guide (August 2017)

By default, including the keyword #review within a changelist description (separated from other text with whitespace, or on a separate line) informs Swarm that a review should begin when the changelist is shelved or committed. Once a review has begun, Swarm adjusts the keyword with the review's identifier, such as #review-1234. This adjustment informs Swarm which review should be updated whenever the original changelist is re-shelved or committed.

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(
            // #review or #review-1234 with surrounding whitespace/eol
            'octothorpe'      => array(
                'regex'  => '/(?P<pre>\s+|^)'
                         .  '\#(?P<keyword>review)(?:-(?P<id>[0-9]+))?'
                         .  '(?P<post>\s+|$)/i',
                'spec'   => '%pre%#%keyword%-%id%%post%',
                'insert' => "%description%\n\n#review-%id%",
                'strip'  => '/^\s*\#review(-[0-9]+)?(\s+|$)'
                         .  '|(\s+|^)\#review(-[0-9]+)?\s*$/i',
            ),

            // [review] or [review-1234] at start
            'leading-square'  => array(
                'regex' => '/^(?P<pre>\s*)'
                        .  '\[(?P<keyword>review)(?:-(?P<id>[0-9]+))?\]'
                        .  '(?P<post>\s*)/i',
                'spec'  => '%pre%[%keyword%-%id%]%post%',
            ),

            // [review] or [review-1234] at end
            'trailing-square' => array(
                'regex' => '/(?P<pre>\s*)'
                        .  '\[(?P<keyword>review)(?:-(?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.