モデル
コードレビューモデルには、プリコミットモデル、ポストコミットモデル、Git Fusionモデルの3つがあります。 Swarmのコードレビューで使用するモデルは、ユーザが自由に選択することができます。
プリコミットモデル
プリコミットモデルの場合、Helixサーバの保留機能を使用することができます。 保留機能を使用すると、変更をディポ内にコミットすることなく、自分のファイルのコピーを他のユーザが一時的に使用できるようになります。 開発者がバックアップを作成する場合や、ローカルのワークスペースに対する変更を処理する場合は、保留機能を使用すると便利です。進行中の作業内容を失うことも、コードベースに悪影響を与える可能性のあるコードをコミットする必要もありません。
Swarmは、Helixサーバの保留機能を使用して、コードレビューの管理を行います。 レビュー担当者は、保留機能を使用することにより、レビュー対象のコードのコピーを簡単に取得し、レビュー後のコードを更新してからサブミットすることができます。
保留機能の詳細については、Helix Coreサーバユーザガイドの「チェンジリストを保留する」を参照してください。
ポストコミットモデル
チーム内の開発プロセスで保留機能を使用しない場合は、ポストコミットモデルを使用することができます。 コードレビューを開始する前に、Helixサーバにコードをコミットする必要がありますが、これが原因で、反映に関する問題が継続的に検出される場合などに、問題を修正する機会が減ってしまうことになります。 ただし、コードがいつコミットされたかにかかわらず、既存のコードのレビューをいつでも開始できるという利点があります。
Git Fusionモデル
Perforce Git Fusionには、Gitレポジトリ用のレポジトリ管理機能が不足しています。また、HelixサーバユーザとPerforceユーザが任意のツールを使用して同じプロジェクト上でコラボレーションを行うためのワークフローも用意されています。
Git Fusionモデルは、プリコミットモデルに似ています。ローカルレポジトリ内の変更を、Git Fusionレポジトリ構成内の特定のHelixサーバブランチにプッシュして、目的の変更を使用可能な状態にすることができます。これにより、その変更を反映先ブランチにコミットする前に、他のユーザがその変更をレビューしてコメントを追加できるようになります。 Git FusionとSwarmは相互に連携して、プリコミットコラボレーション用のレビューブランチとコンテナを作成します。
Git Fusionモデルには、以下に示す制限事項があります。
-
Git Fusionで作成されたレビューに対する反映先ブランチには、すべてのデータが取り込まれている必要があります。また、その反映先ブランチが、レポジトリ固有のGit Fusion構成内に登録されている必要があります。
軽量ブランチを完全実装版のHelixサーバブランチに変換する方法については、Git Fusionガイドの「レポジトリの設定」を参照してください。
- Git Fusionで作成されたレビューは、Git Fusion以外では更新できません。
- 同じレビューの履歴を削除して変更をプッシュすることはできません。 Gitリベースを実行する場合は、変更を新しいレビューとしてプッシュする必要があります。
- 現時点では、Git Fusionで作成されたレビューには、そのレビューを構成する個々のタスクブランチコミットは表示されません。 代わりに、マージ後のコミットの差分のみが表示されます。
Git Fusionの詳細については、『Git Fusionガイド』を参照してください。
内部処理
Swarmが管理するチェンジリスト
コードレビューは、Swarmが管理する1つ以上の保留状態のチェンジリストから構成されます。 保留状態のチェンジリストとは、そのチェンジリストに関連付けられているシェルフ上にファイルのスナップショットが存在する作業中のチェンジリストのことです。
レビューを開始すると、Swarmによって新しいチェンジリストが作成され、このチェンジリストがレビュー用のチェンジリストになります。 その後に実行される処理は、状況に応じて以下のようになります。
- コミットされていない作業内容がレビューに含まれている場合(プリコミットモデル)、Swarmでは、保留中のファイルが、レビューを開始したユーザのチェンジリストからレビュー用のチェンジリストにコピーされます。
- レビューに関連付けられているユーザのチェンジリストの保留中ファイルを更新するたびに、Swarmでは、そのファイルがレビュー用のチェンジリストにコピーされ、アーカイブチェンジリストが作成されます。 アーカイブチェンジリストは、保留状態のファイルが存在する作業中チェンジリストと同じですが、アーカイブチェンジリストにより、Swarmのレビュー内でバージョン管理と差分の作成を行うことができるようになります。
- レビューの最新バージョンをコミットすると(ポストコミットモデル)、レビュー用のチェンジリストからすべてのファイルが削除されます。
ただし、レビュー用のチェンジリストが実際にコミットされるわけではないため、保留中の変更が追加された場合に、後からレビューを作業状態にすることができます。
Swarmをアンインストールする場合を除き、Swarmが管理するレビュー用チェンジリストは削除しないでください。
Swarmが管理するレビュー用チェンジリストには、レビューの履歴と、そのレビューに対するすべてのフィードバックが保管されます。 Swarmの保留状態のチェンジリストを削除すると、システムの動作が不安定になり、データの損失が発生する可能性があります。また、Perforceの担当者でも復旧が困難な問題が発生する可能性があります。
p4 changelists
コマンドを使用すると、Swarmが管理するすべてのチェンジリストの一覧を表示することができます。
$
p4 changelists -u swarm
Change 1212285 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructions'
Change 1212284 on 2015/07/31 by swarm@swarm-96017af4-5615-9819-7af1-6fc1fa537214 *pending* 'Add requirements and instructions'
...
「swarm」は、Swarmを使用するように構成されているHelixサーバ内でadminレベルの権限が割り当てられているユーザのIDです。 p4 changelists
コマンドを実行する場合は、適切なユーザIDを使用してください。
Swarmが管理するワークスペース
Swarmは、レビュー用のチェンジリストを作成する際に、admin権限を持つ構成済みHelixサーバユーザIDに関連付けられているクライアントワークスペース(またはワークスペース)を使用します。 特定のユーザがSwarmのユーザインタフェースを使用して変更をコミットするたびに、そのユーザに関連付けられているワークスペースがSwarmで使用されます。
ワークスペースの詳細については、『ソリューション概要: Helixバージョンコントロールシステム』のガイドの「バージョン管理実装としてのHelixサーバ」を参照してください。
Swarmが作成して使用するワークスペースは、SWARM_ROOT/data/clients
フォルダに保存されます。
Swarmはこのclientsフォルダを使用して、必要なワークスペースフォルダが保存されているユーザ固有のフォルダを管理します。 ユーザ固有の各フォルダには、HelixサーバのユーザIDを16進数に変換した値が、フォルダ名として設定されます。これは、スラッシュ、アクセント記号、UTF-8文字列など、ファイルシステム内で問題が発生する可能性のある文字の使用を避けるためです。 例えば、「steve.russell」という名前のユーザの場合、フォルダ名は「73746576652e72757373656c6c
」になります。
ユーザ固有のフォルダには、各ワークスペースのルートフォルダになるフォルダが保管されます。 これらの各フォルダでは、swarm-438d482b-f107-9a35-c06c-86ac68136b00
などのように、swarm
というプレフィックスが指定されたグローバル一意識別子(GUID)を使用して、フォルダ名が設定されます。 各フォルダには、フォルダ名に「.lock」という拡張子が付加されたロックファイルが付属しています。 ユーザ固有のクライアントフォルダには、manage.lock
という名前の管理ロックファイルが保存されます。
以下に、フォルダ構造の例を示します。
SWARM_ROOT/
data/
clients/
73746576652e72757373656c6c/
manage.lock
swarm-438d482b-f107-9a35-c06c-86ac68136b00/
swarm-438d482b-f107-9a35-c06c-86ac68136b00.lock
swarm-8388362a-233d-0cb9-3e90-895eaaa99f6c/
swarm-8388362a-233d-0cb9-3e90-895eaaa99f6c.lock
7061756c612e626f796c65/
manage.lock
swarm-da7de4b4-0ecb-12c8-1b35-f3e32bb18033/
swarm-da7de4b4-0ecb-12c8-1b35-f3e32bb18033.lock
Swarmは、以下の手順でクライアントを使用します。
- 現在の接続のユーザIDを16進数に変換します。
- ユーザ固有のフォルダが
SWARM_ROOT/data/clients
フォルダ内に存在するかどうかを確認し、存在しない場合は新しく作成します。 -
ユーザ固有のフォルダ内で、既存のワークスペースフォルダをループし、以下の方法で各フォルダをロックします。
ロックが取得できた場合は、手順4に進みます。 取得できなかった場合は、以下の手順を実行します。
ワークスペースの作成手順
-
現在のユーザに対する最大クライアント数に達していないかどうかを確認します。
- 最大数に達している場合は、50ミリ秒間待機してから、手順3をもう一度実行します。
- 最大数に達していない場合は、次の手順に進みます。
manage.lock
ファイルをロックします。-
現在のユーザに対する最大クライアント数に達していないかどうかを確認します。
- 最大数に達している場合は、
manage.lock
ファイルのロックを解除し、50ミリ秒間待機してから、手順3をもう一度実行します。 - 最大数に達していない場合は、次の手順に進みます。
- 最大数に達している場合は、
- GUIDベースのファイル名を使用して新しいワークスペースフォルダを作成し、そのフォルダをロックします。
manage.lock
ファイルのロックを解除します。
-
- ロックされているワークスペースフォルダを使用して、必要なファイル操作を実行します。
-
ディスクスペースの使用量が増え続けるのを防ぐため、ワークスペースフォルダ内のファイルの内容を元に戻します。
注意孤立したファイルが残ってしまう場合がありますが、こうしたファイルがSwarmによってクリーンアップされることはありません。
- Swarmにより、ワークスペースフォルダのロックが解除されます。
ほとんどのユーザの場合、必要になるワークスペースの数は1つまたは2つです。ワークスペースが必要になるのは、Swarmからコミットを実行する場合のみです。 Swarmを使用するように設定されているadminユーザは、構成されているワーカーごとに1つのワークスペースを使用する必要があります。
デフォルトでは、特定の時点でアクティブにできるワークスペースの数は、構成されているワーカーの数の2倍です。 デフォルトのワーカー数は3であるため、Swarmでは最大6つのワークスペースを同時に使用できることになります。
ワークスペースの上限数に達した場合は、いずれかのワークスペースが使用可能な状態になるまで、ファイルの処理が停止します。 そのため、ユーザがタイムアウトになる場合があります。 Swarmで使用されるワーカーの数を増やすと、この問題を解決することができます。
削除に関する考慮事項
管理者は、Swarmが管理するワークスペースを削除することができます。 ワークスペースを削除する場合は、以下の考慮事項に注意する必要があります。
-
Swarmが管理するワークスペースをSwarmサーバから削除する前に、Webサーバを停止してSwarmを終了しておくことをお勧めします。こうすることにより、使用中のワークスペースを誤って削除することがなくなります。
最初にWebサーバを停止しないと、サブミット中にSwarmでエラーが発生する可能性があります。
- Swarmが管理するワークスペースフォルダを削除しても、Helixサーバのクライアント仕様は削除されません。 このクライアント仕様を削除しないと、対応するワークスペースが孤立することになります。 ただし、ストレージとパフォーマンスに対する影響はほとんどないため、孤立したクライアント自体は大きな問題にはなりません。
-
Swarmが管理するワークスペースに対応するHelixサーバのクライアント仕様は、削除することができます。 ただし、保留中のファイルに関連付けられているクライアント仕様は削除しないでください。
通常は、保留中のファイルが関連付けられているクライアント仕様のみが、Swarmを使用するように構成されているadminアカウントに属することになります。 その他すべてのワークスペース(管理者以外のユーザが使用するワークスペース)は、主に変更をサブミットする目的で使用されるため、通常は、保留中のファイルが関連付けられることはありません。