バグ追跡ツール/課題追跡システムとの統合

ソフトウェア開発ではふつう、変更を特定のバグIDや課題IDに結びつけます。バグ追跡ツール(課題追跡システム)を使用している場合、 Subversion で行った変更を、課題追跡システムの特定のIDと関連付けできると便利です。多くの課題追跡システムではそのために、ログメッセージを解釈してコミットに関連する課題IDを抽出するための pre-commit フックスクリプトを提供しています。しかし、 pre-commit フックスクリプトが正しく解釈できるようにログメッセージを書けるかどうかはユーザーに依存しているため、ときどき失敗する傾向があります。

TortoiseSVN は、次の2つの方法でユーザーを補助します。

  1. ユーザーがログメッセージを入力するとき、課題IDを含む行が自動的に正しい書式で追加されるようにします。これによって、ユーザーがバグ追跡ツールで正しく解釈できない形で課題IDを入力してしまうリスクを減らせます。

    また、 TortoiseSVN は入力されたログメッセージのうち、課題追跡システムが認識した部分を強調表示できます。これにより、ログメッセージが正しく解釈されたか、ユーザーが知ることができます。

  2. ユーザーがログメッセージを閲覧する際に、 TortoiseSVN は、ログメッセージ内の各課題IDに、課題に言及しているページをブラウザーで開くリンクを作成します。

ログメッセージへの課題IDの付与

TortoiseSVN は任意のバグ追跡ツールと統合できます。そのためには、 bugtraq: で始まるプロパティを、フォルダーに対して定義する必要があります。(「プロジェクト設定」

図4.67 課題追跡システムのプロパティダイアログ

課題追跡システムのプロパティダイアログ


課題追跡システムのプロパティを編集する場合、適切な値を簡単に設定するために、専用のプロパティエディターを使用します。

TortoiseSVN と課題追跡システムを統合するには、2つ方法があります。ひとつは単純文字列による方法、もうひとつは 正規表現 による方法です。プロパティにはどちらの方法も使用できます。

bugtraq:url

バグ追跡ツールのURLを設定します。適切にURIエンコードし、中に %BUGID% を含む必要があります。 %BUGID% は入力された課題IDに置き換えられます。これによって TortoiseSVN のログダイアログ上にリンクを表示し、リビジョンログを参照する際に、バグ追跡ツールに直接ジャンプできるようになります。このプロパティがないと、 TortoiseSVN は課題IDを表示するだけで、リンクを表示しません。例えば TortoiseSVN の開発プロジェクトでは、 http://issues.tortoisesvn.net/?do=details&id=%BUGID% という設定を使用しています。

絶対URLの代わりに相対URLも使用できます。これは、課題追跡システムが、自分のソースリポジトリと同じドメインやサーバーにある場合に便利です。ドメイン名を変更したとしても、bugtraq:url プロパティを調整する必要がないからです。相対 URL を指定するには以下の2つの方法があります。

文字列が ^/ で始まる場合は、リポジトリルートからの相対 URL であると見なされます。例えば、リポジトリが http://tortoisesvn.net/svn/trunk/ にある場合、^/../?do=details&id=%BUGID% は、http://tortoisesvn.net/?do=details&id=%BUGID% と解釈されます。

/ で始まる文字列の URL は、サーバーのホスト名からの相対 URL であると見なします。例えば、リポジトリが http://tortoisesvn.net のどこかにある場合、/?do=details&id=%BUGID% は、http://tortoisesvn.net/?do=details&id=%BUGID% と解釈されます。

bugtraq:warnifnoissue

課題IDテキストフィールドが空の場合、TortoiseSVN が警告を発するようにする場合は、 true に設定してください。有効な値は true/false です。 定義されていなければ、 false として扱われます。

テキストボックスを使用した課題ID

単純文字列によるアプローチでは、課題IDを入力できる独立した入力フィールドが表示されます。そして、ユーザーが入力したログメッセージに独立した行が追加されます。

bugtraq:message

入力フィールドモードでバグ追跡システムを有効にします。このプロパティを設定すると、変更をコミットする際に課題IDを入力するよう促されます。この書式でログメッセージの末尾に行が追加されます。中に %BUGID% を含んでいる必要があり、これはコミットの際に課題IDに置換されます。この機能を使用することで、コミットログに課題IDへの参照を一定の書式で確実に含め、バグ管理ツールがこれを解釈して課題IDと特定のコミットを関連付けることができるようになります。例えば Issue : %BUGID% などと設定することができますが、これは使用するツールに依存します。

bugtraq:label

このテキストは、コミットダイアログの課題IDを入力するエディットボックスのラベルとして表示されます。設定されていないと、 バグID/課題番号(): bugtraq:numbertrue true/false true bugtraq:appendtrue/false true

正規表現を使用した課題ID

正規表現 でのアプローチでは、独立した入力フィールドは表示されませんが、ログメッセージを入力中に課題追跡システムによって認識された部分をマークします。これは、ログメッセージの入力中に表示されます。これは課題IDが、ログメッセージのどこにあってもかまわないということです。この方法はとても柔軟で、 TortoiseSVN プロジェクトではこれを使用しています。

bugtraq:logregex

このプロパティを設定すると、 正規表現 モードでバグ追跡システムが有効になります。ここには単一の正規表現か、改行で区切って2つの正規表現を設定できます。

正規表現を2つ設定した場合、1つ目の正規表現は、含まれている課題IDを探すための前処理フィルターとして使用します。2つ目の正規表現は、最初の正規表現の結果から、課題IDのみを抽出します。これにより、課題IDの一覧を抽出したり、自然言語表現から課題IDを抽出したりすることができます。例えば複数のバグを修正し、 This change resolves issues #23, #24 and #25 というような文字列を入力したとします。

このログメッセージの中にある表現から課題IDを抽出するには、[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+(\d+)のような正規表現を使用することができます(TortoiseSVN プロジェクトで使用しているもののひとつです)。

1つ目の正規表現で、ログメッセージから issues #23, #24 and #25 の部分を抜き出します。2つ目の正規表現は、最初の正規表現の出力から、生の十進数の数値を抽出します。つまり、課題IDとして使われている、23, 24, 25 が返ります。

はじめの正規表現を少しかみ砕くと、 issue という単語(先頭が大文字でも可)で始まっていなければなりません。この後にs(複数の場合)やコロンを続けることもできます。この後、0個以上の空白と、オプションのコンマまたは and 、さらに0個以上の空白が来て、さらに#と十進数の数値、という形のグループが1つ以上来ます。

正規表現が1個のみの場合は、単体の課題IDと正規表現文字列のグループとがマッチしなければなりません。例: [Ii]ssue(?:s)? #?(\d+)。この方法は、 trac のような一部の課題追跡システムには必要ですが、その正規表現を構築するのは大変です。使用する課題追跡システムのドキュメントにある場合にのみ、この方法を使用するのをお勧めします。

正規表現になじみがなければ、http://ja.wikipedia.org/wiki/正規表現 にある解説や、http://www.regular-expressions.info/ にあるオンラインのドキュメントやチュートリアルをご覧ください。

正規表現を常に正しく書くことは困難なので、手助けのために、課題追跡システムのプロパティダイアログにテストダイアログを用意しています。エディットボックスの右側のボタンをクリックすると起動します。ここに文字列を入力し、正規表現を変更すると結果を表示させることができます。正規表現が無効であれば、エディットボックスの背景が赤くなります。

bugtraq:messagebugtraq:logregex の両方を設定した場合、logregex が優先されます。

ヒント

ログメッセージを解釈する pre-commit フックスクリプトを持つ課題追跡システムがなくても、ログメッセージで言及している問題にリンクするために、この機能を使用することができます。

またリンクが必要なくても、課題IDがログダイアログの独立した列に表示されるので、どの課題に対応する変更かがわかりやすくなります。

tsvn: プロパティのいくつかは true/false 値をとります。TortoiseSVN は yestrue と同義に、nofalse と同義に解釈します。

フォルダーへのプロパティの設定

これらのプロパティは、作業するシステムのフォルダーに設定しなければなりません。ファイルやフォルダーをコミットする際に、このフォルダーからプロパティが読み取られます。フォルダーにプロパティが設定されていない場合、プロパティはフォルダー階層を上位に向かって、バージョン管理外フォルダーか、ツリーのルート(例: C:\)に到達するまで検索されます。すべてのユーザーが、例えば trunk/ からチェックアウトし、サブフォルダーからチェックアウトしないことが確認できるのであれば、 trunk/ にそのプロパティを設定するだけで充分です。サブフォルダーからもチェックアウトする可能性があるのであれば、プロパティを各サブフォルダーに再帰的に設定するべきです。プロジェクトの深い階層で設定されたプロパティは、高いレベルの(trunk/ に近い)ものより優先されます。

プロジェクトプロパティ(例:tsvn:bugtraq:webviewer:)に限っていえば、 プロパティを再帰的に適用する チェックボックスを使うと、そのフォルダ以下のすべてのサブフォルダーにプロパティを設定しますが、ファイルには設定しません。

TortoiseSVN で新しいサブフォルダーを作業コピーに追加する際、親フォルダーに設定されているプロジェクトプロパティは、新しいサブフォルダーにも自動的に追加されます。

リポジトリブラウザーからは課題追跡システムの情報を利用できない

バグ追跡システムとの統合は、 Subversion のプロパティとして保持されているため、チェックアウトした作業コピーを使用するときのみ表示されます。リモートからプロパティを取得するのには時間がかかるため、作業コピーからリポジトリブラウザーを起動しなければ表示されません。リポジトリのURLを入力してリポジトリブラウザーを起動した場合は表示されません。

同じ理由で、プロジェクトのプロパティは、リポジトリブラウザーを使用して子フォルダーを追加しても、自動的には継承されません。

この課題追跡システムとの統合は、 TortoiseSVN に限定されたものではなく、どの Subversion クライアントでも共通で使用できます。これについての詳細は、TortoiseSVN のソースリポジトリにある、Issue Tracker Integration Specificationの全文をお読みください(リポジトリへのアクセスのしかたは、 「ライセンス」で説明します)。

課題追跡システムからの情報取得

前節では、ログメッセージへ課題情報の追加について扱いました。しかし、課題追跡システムから情報を取得する必要がある場合、どのようにしたらよいのでしょう?コミットダイアログは、課題追跡システムと対話できるような、外部プログラムを統合するためのCOMインターフェイスを備えています。通常、自分に割り当てられた未解決の課題の一覧を問い合わせて、このコミットに関連する課題を選択できるといいのではないでしょうか。

そのようなインターフェイスはいずれも、課題追跡システムに強く依存しているので、私たちはこの部分を提供することはできませんし、そのようなプログラムの作成方法について説明することは、このマニュアルの範疇を超えてしまいます。インターフェイスの定義や、C#やC++/ATLで書かれたサンプルプラグインは、TortoiseSVN リポジトリcontrib フォルダーから取得できます(リポジトリのアクセスの仕方は、 「ライセンス」で説明します)。API の概要も 6章IBugtraqProvider インターフェイス で得られます。それ以外の(動作する)サンプルプラグインとして、 C# では Gurtle があり、これは課題管理システム Google Code と連動するために必要な COM インターフェイスを実装しています。

説明のために、システム管理者が、インストールした課題管理システムプラグインを提供し、 TortoiseSVN の設定ダイアログでそのプラグインを使用する作業コピーをセットアップしたとしましょう。プラグインに割り当てられた作業コピーからコミットダイアログを開くと、ダイアログの上部に新しいボタンが現れるはずです。

図4.68 課題追跡システムクエリダイアログの例

課題追跡システムクエリダイアログの例


この例では、複数の未解決課題を選択できます。その後、プラグインがログメッセージに追加する、特定のフォーマットのテキストを生成できます。