レビューキーワード

このセクションでは、キーワードの設定方法、チェンジリストの説明内でキーワードを使用してレビューを作成する方法、レビューにチェンジリストを追加する方法について説明します。

レビューキーワードの設定

キーワードは、正規表現を使用して設定できるため、ほとんどのキーワード構文を使用することができます。レビューキーワードをカスタマイズする場合は、予期しない動作がSwarmで発生することを防ぐため、チェンジリスト内で使用されることのない構文と用語を使用してください。

レビューキーワードを設定するには、以下のコードブロックをSWARM_ROOT/data/config.phpファイルに追加します。

<?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%',
            ),
        ),
    ),

複数のパターンを指定することができます。最初に一致したパターンが使用され、残りのパターンは評価されません。

キーワードのタイプは、キーワードのIDでグループ化されます。各グループのregex 項目により、チェンジリストの説明内で指定されているレビューキーワードを特定するための正規表現を指定します。レビューキーワードを更新する必要がある場合は、spec項目を使用します。

octothorpeというレビューキーワード(ハッシュタグ)の場合、チェンジリストの説明内の任意の場所でキャプチャグループやプレースホルダーを指定することができます。チェンジリストの説明の先頭や末尾にキーワードが指定されている場合は、strip 項目を使用して、そのキーワードをレビューの説明から削除します。現在、insert 項目は使用されていません。上記のサンプルコードでは、今後アップグレードを実行する際に発生する可能性のある問題を防ぐために、この項目が使用されています。レビューが開始されていて、チェンジリストの説明内にレビューキーワードがまだ指定されていない場合に、insert項目を使用して、レビューキーワードをチェンジリストの説明に追加します。

指定したキャプチャグループをPHPで使用する方法については、http://www.regular-expressions.info/named.htmlを参照してください。

レビューの作成

デフォルトでは、チェンジリストの説明で#reviewというキーワードを指定すると(他のテキストとの間に空白を入れるか、他のテキストとは別の行に指定する必要があります)、そのチェンジリストが保留またはコミットされたときに、Swarmによってレビューが開始されます。

レビューが開始されると、Swarmにより、#review-1234などのレビューIDが#reviewキーワードに追加されます。これにより、元のチェンジリストがもう一度保留またはコミットされるたびに、更新する必要があるレビューがSwarmに通知されます。

レビューにチェンジリストを追加する

レビューが開始されると、そのレビューにチェンジリストを追加できるようになります。既存のレビューにチェンジリストを追加すると、便利な場合があります。例えば、レビュー内のファイルを後から変更する場合や、複数のチェンジリストを1つのレビューとしてグループ化する場合は、既存のレビューにチェンジリストを追加すると便利です。

デフォルトの場合、チェンジリストの説明内で、レビューID とともに3つのキーワード(#append-、#replace-、#review-)を使用して、既存のレビューにチェンジリストを追加することができます(レビューIDを指定する場合は、他のテキストとの間に空白を挿入するか、別の行に入力する必要があります)。使用できるオプションは、対象となるレビューがプリコミットレビューなのかポストコミットレビューなのかによって異なります。

• プリコミットレビューの場合:
  • 「#append- + レビューID」という形式のオプションを指定することができます。appendオプションを使用してレビューにチェンジリストを追加すると、そのチェンジリスト内のファイルが、レビュー内の既存のファイルに追加されます。これにより、レビューのデフォルトの追加モードがappendモードに変更されます。
  • 「#replace- + レビューID」という形式のオプションを指定することができます。replaceオプションを使用してレビューにチェンジリストを追加すると、そのチェンジリスト内のファイルにより、レビュー内のすべてのファイルが置き換えられます。これにより、レビューのデフォルトの追加モードがreplaceモードに変更されます。
  注意

  コミット済みチェンジリストでプリコミットレビューを置き換えると、そのレビューの新しいバージョンとして、ポストコミットレビューが作成されます。

  • 「#review- + レビューID」という形式のオプションを指定することができます。このオプションを使用してレビューにチェンジリストを追加する場合、そのレビューのデフォルトの追加メソッドが使用されます。デフォルトの追加方法として、replaceオプションまたはappendオプションを指定することができます。レビュー内で最後に使用された追加方法が、デフォルトの追加方法として設定されます。
    • 初めてレビューを作成すると、そのレビューのデフォルトの追加モードとしてreplaceモードが設定されます。
    • appendオプションを使用してレビューにチェンジリストを追加すると、そのレビューのデフォルトの追加モードがappendモードに設定されます。
    • replaceオプションを使用してレビューにチェンジリストを追加すると、そのレビューのデフォルトの追加モードがreplaceモードに設定されます。
    • レビューの現在のデフォルトの追加モードが不明な場合は、#review-キーワードを削除し、「#append- + レビューID」または「#replace- + レビューID」という形式のオプションを指定して、目的の追加モードを設定します。
• ポストコミットレビューの場合:
  • 「#review-」または「#replace- + レビューID」という形式のオプションを指定します。 replaceオプションを使用してレビューにチェンジリストを追加すると、そのチェンジリスト内のファイルにより、レビュー内のすべてのファイルが置き換えられます。
  注意

  作業中チェンジリストでポストコミットレビューを置き換えると、そのレビューの新しいバージョンとして、プリコミットレビューが作成されます。

例:「1234」というIDを持つレビューにチェンジリストを追加する

「#append-1234」というオプションを、チェンジリストの説明に追加します。

• 元のレビューには、次のファイルが含まれています: ファイルA^#1、ファイルB^#2、ファイルC^#1、ファイルD^#1、ファイルE^#4
• チェンジリストには、次のファイルが含まれています: ファイルA^#2、ファイルC^#3、ファイルE^#4 (削除目的でマーキング)、ファイルF^#1
• このチェンジリストを元のレビューに追加すると、次のファイルが含まれている新しいレビューリビジョンが生成されます: ファイルA^#2、ファイルB^#2、ファイルC^#3、ファイルD^#1、ファイルE^#4 (削除目的でマーキング)、ファイルF^#1

例:「1234」というIDを持つレビュー内のファイルをチェンジリスト内のファイルで置き換える

「#replace-1234」というオプションを、チェンジリストの説明に追加します。

• 元のレビューには、次のファイルが含まれています: ファイルA^#1、ファイルB^#2、ファイルC^#1、ファイルD^#1、ファイルE^#4
• チェンジリストには、次のファイルが含まれています: ファイルA^#2、ファイルC^#3、ファイルE^#4 (削除目的でマーキング)、ファイルF^#1
• このチェンジリストで元のチェンジリストを置き換えると、次のファイルが含まれている新しいレビューリビジョンが生成されます: ファイルA^#2、ファイルC^#3、ファイルE^#4 (削除目的でマーキング)、ファイルF^#1

キーワードワークフロー

キーワードを使用するワークフローの例については、「Swarmの外部でレビューの作成と変更を行う」を参照してください。

レビューの説明から@mentionを削除する

以下の例は、レビューの説明に@mentionが追加されないように、patternsブロックで正規表現を使用して、チェンジリストの説明に含まれている@mentionを削除する方法を示しています。

SWARM_ROOT/data/config.phpファイルに以下のブロックを追加します。

<?php
    // this block should be a peer of 'p4'
    'reviews' => array(
        'patterns' => array( 
            'mentions'  => array(
                'regex' => '/(?P<mention>\s@\S+$|@\S+($|\s))/',
                'spec'  => '%mention%'
            ),
        ),
    ),

例

上記のパターンを以下のチェンジリストの説明に対して使用する:

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

チェンジリストが保留されている場合は、以下のようになります。

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

レビューの説明は以下のようになります。

Updated copyright date to 2021.