Helix Swarm管理者ガイド (2020.1)

レビューキーワード

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

ヒント

構成情報を変更しても、構成キャッシュを再ロードしない限り、その構成情報がSwarmで使用されることはありません。構成キャッシュを再ロードすると、変更した構成情報がSwarmで強制的に使用されます。 Swarm構成キャッシュを再ロードするには、admin ユーザまたはsuper ユーザでなくてはなりません。 [ユーザID]ドロップダウンメニューに移動して[システム情報]を選択し、[キャッシュ情報]タブをクリックしてから[構成の再ロード]ボタンをクリックします。

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

キーワードは、正規表現を使用して設定できるため、ほとんどのキーワード構文を使用することができます。レビューキーワードをカスタマイズする場合は、予期しない動作が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項目を使用します。

注意

上記のサンプルコードのregexでは、「(?<pre>\s*)」などのように、名前付きキャプチャグループが使用されています。正規表現によるマッチング処理で取得された値を使用して、spec項目の「%」で囲まれたプレースホルダーの値が置き換えられます。上記のサンプルコードでは、preキャプチャグループ、postキャプチャグループ、各種のプレースホルダーを使用して、レビューキーワードの前後に空白を挿入しています。

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

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

レビューを作成

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

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

注意

プリコミットレビューを作成し、別のユーザがそのレビューにチェンジリストを追加すると、レビューのデフォルトの追加モードが、replaceモードからappendモードに変更されます。詳細については、「レビューにチェンジリストを追加する」を参照してください。
Swarmは、チェンジリストの説明内で最初に見つかった有効なキーワードに対して処理を実行します。それ以降は、説明内で有効なキーワードが見つかっても、Swarmはそれらのキーワードをすべて無視します。
Swarmでは、チェンジリストの説明の先頭または末尾に[review]を指定することもできますが、この形式のレビューキーワードは今後のSwarmバージョンで削除される予定になっているため、使用することはお勧めしません。

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

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

注意

すでに特定のレビューに追加されているチェンジリストを別のレビューに追加することはできません。追加しようとすると、Swarmによって拒否されます。

注意

Swarmは、チェンジリストの説明内で最初に見つかった有効なキーワードに対して処理を実行します。それ以降は、説明内で有効なキーワードが見つかっても、Swarmはそれらのキーワードをすべて無視します。

デフォルトの場合、チェンジリストの説明内で、レビュー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- + レビューID」または「#replace- + レビューID」という形式のオプションを指定します。 replaceオプションを使用してレビューにチェンジリストを追加すると、そのチェンジリスト内のファイルにより、レビュー内のすべてのファイルが置き換えられます。

ヒント

レビューの内容を変更すると、Swarmは、そのレビュー内の新しいリビジョンに含まれているブランチを確認します。

新しいブランチをレビューに追加すると、以下のような動作になります。
- 新しいブランチのデフォルトのレビュー担当者がレビューに追加されます。
- 新しいブランチのモデレータが、既存のモデレータとともに、レビューのモデレータになります。
- ワークフローが有効になっている場合のみ: 新しいブランチが特定のワークフローに関連付けられている場合は、そのワークフローが既存のワークフローにマージされます。この場合、最も制限の厳しいワークフローがレビューで使用されます。
ブランチをレビューから削除すると、以下のような動作になります。
- レビューのレビュー担当者は変更されません。
- 削除したブランチのモデレータは、レビューのモデレータではなくなります。
- ワークフローが有効になっている場合のみ: 削除したブランチが特定のワークフローに関連付けられている場合は、そのブランチワークフローがレビューから削除されます。

例: 「1234」というIDを持つレビューにチェンジリストを追加する場合は、以下のような動作になります。

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

元のレビューには、A^#1、B^#2、C^#1、D^#1、E^#4という5つのファイルが含まれています。
追加するチェンジリストには、A^#2、C^#3、E^#4 (削除マーク付き)、F^#1という4つのファイルが含まれています。
上記のチェンジリストを元のレビューに追加すると、そのレビューの新しいリビジョンが生成され、そのリビジョン内に、A^#2、B^#2、C^#3、D^#1、E^#4 (削除マーク付き)、F^#1という6つのファイルが作成されます。

重要

Swarmを使用してレビューをコミットすることをお勧めします。この場合、レビューの承認済みリビジョン内のファイルが、Swarmによって自動的にコミットされます。

Swarmの外部でレビューをコミットする場合は、以下の手順を実行する必要があります。

レビューをコミットする前に、以下の手順を実行します。

レビューの保留を解除して、レビューに関連付けられた作業中チェンジリストの状態に戻します。
作業中チェンジリスト内のファイルを再度保留します。
作業中チェンジリストをコミットします。
このプロセスにより、レビューの承認済みリビジョン内のすべてのファイルがコミットされます。

ワークフロー機能を有効にする(これがデフォルト設定です):

ワークフロールールの[レビューありのコミット時]を使用してSwarmを適切に設定することにより、コミットされるファイルが、レビューの承認済みリビジョン内のファイルと一致しているかどうかを自動的に確認することができます。「レビューありのコミット時」ルールの詳細については、「ワークフロールール」を参照してください。

ワークフロー機能を無効にする:

Swarmを適切に設定し、strictトリガオプションを使用することにより、コミットされるファイルが、レビューの承認済みリビジョン内のファイルと一致しているかどうかを自動的に確認することができます。

例: 「1234」というIDを持つレビュー内のファイルをチェンジリスト内のファイルで置き換える場合は、以下のような動作になります。

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

元のレビューには、A^#1、B^#2、C^#1、D^#1、E^#4という5つのファイルが含まれています。
追加するチェンジリストには、A^#2、C^#3、E^#4 (削除マーク付き)、F^#1という4つのファイルが含まれています。
上記のチェンジリストで元のレビューを置き換えると、そのレビューの新しいリビジョンが生成され、そのリビジョン内に、A^#2、C^#3、E^#4 (削除マーク付き)、F^#1という4つのファイルが作成されます。

ヒント

チェンジリストでレビューを置き換えると、そのレビューの新しいリビジョン内のファイルのベースバージョンが、置き換え元のチェンジリスト内のファイルのベースバージョンになります。

キーワードワークフロー

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

の検索では、個の結果が出ました。