変更が特定のバグ ID や課題 ID に関連するのは、ソフトウェア開発では非常に一般的です。バグ追跡システム (課題追跡システム) のユーザは、課題追跡システムの特定の ID と Subversion で行った変更を関連付けたいと思っています。そのため、ほとんどの課題追跡システムは、コミットに関連するバグ ID を探すためにログメッセージを解釈する、pre-commit フックスクリプトを提供しています。これは、pre-commit フックスクリプトが正しく解釈できるよう、適切なログメッセージを書くようユーザに頼っています。これはいくらか誤る傾向があります。
TortoiseSVN は、以下の 2 種類の方法でユーザの補助を行います。
ユーザがログメッセージを入力すると、コミットに関連付けられた課題番号を含む、よく定義された行が自動で追加されます。これにより、バグ追跡ツールが正しく解釈できない方法で、ユーザが課題番号を入力してしまう危険を減らせます。
また、TortoiseSVN は入力したログメッセージの中で、課題追跡システムが認識した部分を強調表示できます。これにより、ログメッセージが正しく解釈されたか、ユーザが知ることができます。
ユーザがログメッセージを閲覧する際に、TortoiseSVN は、ログメッセージ内の各バグ ID に、課題に言及したページをブラウザで開くリンクを張ります。
TortoiseSVN はいくつかのバグ追跡ツールと統合できます。このとき bugtraq: で始まる属性を使用します。以下のようにフォルダに設定しなければなりません。 (「プロジェクト設定」)
TortoiseSVN と課題追跡システムを統合するには、2 つ方法があります。ひとつは単純な文字列によるもの、もうひとつは 正規表現 によるものです。属性にはどちらの方法も使用できます。
- bugtraq:url
この属性には、バグ追跡ツールの URL を設定します。適切に URI エンコードし、
%BUGID%を含まなければなりません。%BUGID%は入力した課題番号に置換されます。これにより TortoiseSVN はログダイアログにリンクを生成し、リビジョンログ参照時に、バグ追跡ツールへ直接ジャンプできるようになります。この属性がないと、TortoiseSVN は課題番号を表示するだけで、リンクを生成しません。例: 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
課題番号テキストフィールドが空の場合、TortoiseSVN が警告を発するようにしたければ、
trueに設定してください。有効な値はtrue/falseです。 定義されていなければ、falseとして扱います。
シンプルアプローチでは、TortoiseSVN はユーザに、バグ ID を入力できる独立した入力フィールドを表示します。すると、ユーザが入力したログメッセージに独立した行が追加されます。
- bugtraq:message
この属性は、入力フィールドモードでバグ追跡システムを有効にします。この属性が設定されると、変更をコミットする際に、TortoiseSVN は課題番号を入力するよううながします。これはログメッセージの最後に行を追加するのに使用します。コミットの際に課題番号に置換される、
%BUGID%を含まねばなりません。コミットログが課題番号への参照を含むのを確実に行います。課題番号は常に一貫した形式で、特殊なコミットで課題番号を関連付けるよう、バグ追跡ツールが解釈できます。例えばIssue : %BUGID%を使用するはずですが、これは自分のツールに依存します。- bugtraq:append
バグ ID をログメッセージの最後に追加する (true) ときや、ログメッセージの先頭に挿入する (false) ときにこの属性を定義します。有効な値は
true/falseです。 既存のプロジェクトが壊れないよう、これが定義されていない場合、trueとして扱います。- bugtraq:label
このテキストは、TortoiseSVN がコミットダイアログの、課題番号を入力するエディットボックスのラベルに使用されます。設定されていないと、
Bug-ID / Issue-Nr:が表示されます。このラベルにぴったり合うようにウィンドウのサイズ変更ができませんので、ラベルは 20-25 文字以下になるよう留意してください。- bugtraq:number
trueに設定すると、課題番号テキストフィールドには数値しか入力できなくなります。カンマは例外ですので、カンマで区切って複数の数値を入力できます。有効な値はtrue/falseです。 定義されていなければ、trueとして扱います。
正規表現でのアプローチでは、TortoiseSVN は独立した入力フィールドを表示しませんが、ユーザが入力したログメッセージの中の、課題追跡システムに関係する部分をマーク付けします。ログメッセージを入力している間、有効です。これはバグ ID が、ログメッセージのどこにあってもかまわないと言うことです! この方法はとても柔軟で、TortoiseSVN プロジェクトではこれを使用しています。
- bugtraq:logregex
この属性は、正規表現 モードでバグ追跡システムを有効にします。ここには改行で区切っていずれかひとつの正規表現を設定できます。
2 つ正規表現を設定した場合、最初の正規表現を、バグ ID を含む表現を探す、前処理フィルタとして使用します。ふたつ目の正規表現で、はじめの正規表現の結果から、生のバグ ID を抽出します。これにより、お好みでバグIDの一覧と、自然言語表現が利用できます。例えば、いくつかのバグを修正し、「This change resolves issues #23, #24 and #25」 といった文字列を入れたとします。
上記のログメッセージの中にある表現を用いてバグ ID を捕捉するには、以下のような (TortoiseSVN プロジェクトで使用している) 正規表現を使用できます。
[Ii]ssues?:?(\s*(,|and)?\s*#\d+)+と(\d+)です。最初の正規表現で、周囲ののログメッセージから 「issues #23, #24 and #25」 を抜き出します。ふたつ目の正規表現は、最初の正規表現の出力から、生の 10 進の数値を抽出します。つまり、バグ ID として使われている、「23」, 「24」, 「25」 が返ります。
はじめの正規表現を少しかみ砕くと、「issue」 という単語 (先頭が大文字でも可) で始まっていなければなりません。この後に 「s」 が続いてもよく (複数型)、コロンが続いてもよいです。この後には、0 以上の空白が続き、コンマか 「and」 が続いてもよく、その後また 0 以上の空白があるグループが 1 つ以上あります。最後に必ず 「#」 と 10進数の数値が来ます。
正規表現が 1 個のみの場合は、むき出しのバグ ID と正規表現文字列のグループとがマッチしなければなりません。例:
[Ii]ssue(?:s)? #?(\d+)。この方法は、trac のような少数の課題追跡システムには必要ですが、その正規表現を構築するのは大変です。あなたの使用する課題追跡システムのドキュメントにある場合にのみ、この方法を使用するのをお勧めします。正規表現になじみがなければ、http://ja.wikipedia.org/wiki/正規表現 にある導入や、http://www.regular-expressions.info/ にあるオンラインのドキュメントやチュートリアルをご覧ください。
bugtraq:message と bugtraq:logregex の両方をセットしている場合、logregex を優先します。
ヒント
pre-commit フックスクリプトで解釈していれば、課題追跡システムがない場合でも、ログメッセージ内の課題に言及している箇所を、リンクにするために使用できます!
またリンクが必要なくても、課題番号がログダイアログの独立した列に表示されるので、どの課題に対応する変更かがわかりやすくなります。
tsvn: 属性のいくつかは true/false 値をとります。TortoiseSVN は yes を true と同義に、no を false と同義に解釈します。
フォルダへの属性の設定
システムが動作するのに、上記の属性はフォルダにセットしなければなりません。ファイルやフォルダをコミットする際に、このフォルダから属性が読み込まれます。そこに属性がない場合、TortoiseSVN は、バージョン管理外フォルダか、ツリーのルート (例: C:\) に行き着くまで、フォルダツリーをさかのぼって探します。ユーザがそれぞれ、例えばtrunk/ からのみチェックアウトして、サブフォルダを含まないことが確かならば、trunk/ にのみセットすれば十分です。確かでなければ、各サブフォルダに再帰的に属性を設定する必要があります。プロジェクト階層の深いところで設定された属性は、高いレベル (trunk/ に近い) のものを上書きします。
tsvn: 属性 だけ ですが、再帰チェックボックスを使って階層の全サブフォルダに属性をセットできます。このとき全ファイルが対象になるわけではありません。
リポジトリブラウザから課題追跡システムの情報を利用できません
課題追跡システムとの統合は、subversion の属性にアクセスできることに依存しているため、チェックアウトした作業コピーを使用するときにだけ、結果を目にするでしょう。リモートから属性を取得するのは遅い操作ですので、作動中のこの機能をリポジトリブラウザから目にすることはないでしょう。
この課題追跡システムとの統合は、TortoiseSVN に限定されていません。ですから、いずれの Subversion クライアントでも使用できます。詳細は、TortoiseSVN のソースリポジトリにある、Issue Tracker Integration Specification の全体をお読みください (リポジトリのアクセスのしかたは 「TortoiseSVN は自由!」 で説明します)。
前節では、ログメッセージへ課題情報の追加について扱いました。しかし、課題追跡システムから情報を取得する必要がある場合、どのようにしたらよいのでしょう? コミットダイアログは、課題追跡システムと会話ができるような、外部プログラムを統合する COM インターフェースを備えています。通常、今回のコミットで取り組む課題を取り上げられるように、自分に割り当てられた未解決の課題を取得するよう、課題追跡システムに問い合わせを行うのでしょう。
Any such interface is of course highly specific to your issue tracker system, so we cannot provide this part, and describing how to create such a program is beyond the scope of this manual. The interface definition and sample plugins in C# and C++/ATL can be obtained from the contrib folder in the TortoiseSVN repository. (「TortoiseSVN は自由!」 explains how to access the repository). A summary of the API is also given in 6章IBugtraqProvider インターフェース Another (working) example plugin in C# is Gurtle which implements the required COM interface to interact with the Google Code issue tracker.
説明のために、あなたのシステム管理者が、あなたがインストールした課題管理システムプラグインを提供し、TortoiseSVN の設定ダイアログでそのプラグインを使用する作業コピーをセットアップしたとしましょう。プラグインに割り当てられた作業コピーからコミットダイアログを開くと、ダイアログの上部に新しいボタンが現れるはずです。
この例では、複数の未解決課題を選択できます。その後、プラグインがログメッセージに追加する、特定のフォーマットのテキストを生成できます。