ソースコード・バグ・コンテンツ管理システムの統合

ソースコード管理システム Mercurial，バグ管理システム Mantis Bug Tracker (MantisBT)，コンテンツ管理システム DokuWiki を統合してみました。使用したバージョンは下記の通りです。

Mercurial 1.4.2
MantisBT 1.2.0rc2
DokuWiki 2009-12-25b

各システムのインストール

省略。 Mercurial については easy_install でインストール、 DokuWiki についてはアーカイブを解凍するだけです。 MantisBT は SQL サーバーの設定が必要ですが省略します。

なお，いずれも同一サーバーにインストールされていることを仮定します。また， Mercurial は中央リポジトリとして扱うものとします (次項)。

Mercurial + MantisBT

Mercurial を中央リポジトリとして，ローカルブランチから push された際に変更を MantisBT に通知します。通知には php をコマンドラインから使用できる必要がありますので， php-cli をインストールしておきます。

MantisBT の設定

MantisBT に変更を通知するユーザーを用意します。仮に vcs とします。注意する点は，どのユーザーが push してもこのユーザーが MantisBT に変更を通知します。したがってこのユーザーはすべてのチケットにコメントを付けることができなければなりません。マニュアルでは DEVELOPER レベルが推奨されています。

config_inc.php に以下の行を追加します。

$g_source_control_account = 'vcs';

デフォルトではコミットコメント中に "issue #1" のような文字列が含まれている場合に通知が行われます。また，チケットステータスの自動変化は行われず，コメントは非公開です。

詳しくはマニュアルの「ソース管理との統合」を参照してください。

Mercurial の設定

push された際に起こるイベントは incoming です。設定ファイル .hg/hgrc に以下の記述をします。

[hooks]
incoming.mantis = /path/to/hook

/path/to/hook は MantisBT に通知するためのスクリプトファイルです。実行権限が必要です。スクリプトでは MantisBT の checkin.php に標準入力でコメントを渡します。実際には次のようになります。

#!/bin/sh

hg log -r $HG_NODE | /path/to/php /path/to/mantisbt/scripts/checkin.php
exit $?

最後の exit $? でチェックインに失敗した際にスクリプトを異常終了させます。まとめて push してもそれぞれのコミットに対応するチケットのみにチェックインされます。途中で失敗した場合はどうなるのかわかりません。

出力されるメッセージの形式については Customizing the output of Mercurial を参照してください。必要ならコミットメッセージに対応するチケットがない場合はエラーとなるようにするのが良いと思います。

Mercurial サーバーと MantisBT サーバーが異なるマシンである場合， MantisBT の checkin.php を修正して， HTTP の POST でメッセージが受け取れるようにすれば良いと思いますが，試していません。

MantisBT + DokuWiki

MantisBT にチケットもしくはプロジェクトに対応する Wiki ページへのリンクを貼ることができます。チケット固有の話題を詳細に書きたい場合なんかに便利だと思います。また， MantisBT のログイン情報を Wiki と共有できます。

MantisBT 1.2 から Wiki との統合が容易になっています。 1.1 の場合は MantisBT のファイルも修正する必要がありますが， 1.2 からは MantisBT 側の作業はほとんどありません。ちなみに DokuWiki 以外にも MediaWiki， TWiki， WikkaWIki， XWiki にデフォルトで対応しています。

Mantis の設定

config_inc.php に以下の行を追加します。

$g_wiki_enable = ON;
$g_wiki_engine = 'dokuwiki';
// ルート名前空間が必要ないなら空文字列 '' を指定する。
$g_wiki_root_namespace = 'mantisbt';
// 必要に応じて Wiki の絶対 URI になるように修正する。
$g_wiki_engine_url = $t_protocol . '://' . $t_host . "/%wiki_engine%/';

DokuWiki の設定

おおむね Integrating DokuWiki with Mantis の DokuWiki Steps に書いてある通りです。

Configuration

以下の行を conf/dokuwiki.php に追加します。

MantisBT のインストールディレクトリ。最後のスラッシュは必須。
define( 'MANTIS_ROOT', '/path/to/mantisbt/' );
// MantisBT の絶対 URI。最後のスラッシュは必須。
define( 'MANTIS_URL', 'http://www.example.com/mantisbt/' );

以下の行を conf/local.php に追加もしくは編集します。

$conf['useacl'] = 1;
$conf['authtype'] = 'mantis';
$conf['defaultgroup'] = '@VIEWER';
$conf['superuser'] = '@ADMINISTRATOR';

conf/dokuwiki.php は DokuWiki をアップグレードすると上書きされますのでその都度修正が必要です。単に使った最新版の発行ミスかもしれませんが。

Authentication

Authentication に書かれたコードをコピーして inc/auth/mantis.class.php に保存します。

Mantis Syntax Plug-in

Mantis Syntax Plug-in に書かれたコードをコピーして lib/plugins/mantis/syntax.php に保存します。

DokuWiki 内で ~~Mantis:1~~ のように記述すれば対応するチケットにリンクします。最後に少し触れますが， PHP ファイルを編集して， "Mantis" の部分は "issue" などのより一般的な単語で書けたほうが嬉しいです。

Authorisation Configuration

conf/acl.auth.php に以下の行を追加もしくは編集します。

# none   0
# read   1
# edit   2
# create 4
# upload 8
# delete 16

* @VIEWER 1
* @REPORTER 1
* @DEVELOPER 4
* @MANAGER 8
* @ADMINISTRATOR 16
* @ALL 0

# から始まる行は権限の説明です。必要に応じて権限レベルを編集する必要があります。

なお，このファイルもアップグレード時に上書きされていました。

XML-RPC を用いて Wiki の編集が行えますので， Mercurial のコメントをポストするようなことを行うのが正しい使い方なのかもしれません。

アップグレードとシステムの移行

アップグレードの際に上書きされてしまう設定ファイルがあるのは厄介ですね。しかし DokuWiki 以外についてはアップグレードの問題は大きな変更がなければ大丈夫ではないでしょうか。

バージョン管理，バグ管理，コンテンツ管理のいずれかのシステムを別のシステムに置き換えるときはどうでしょうか。簡単に変更点をまとめてみました。

移行するシステム	変更点
移行するシステム	Mercurial	MantisBT	DokuWiki
Mercurial	-	不要	リポジトリへのリンク
MantisBT	フックスクリプト	-	ユーザー権限，チケットへのリンク
DokuWiki	不要	`$g_wiki_engine`	-

DokuWiki の受ける影響は大きいです。ユーザー権限に関しては最初から LDAP を使えば問題なさそうです。そうでない場合はちまちま移行する必要がありそうですが，何か良い方法があるのでしょうか。チケットのリンクに関しては Mantis Syntax Plug-in を少し修正すればなんとかなりそうです。リポジトリへのリンクについては，バージョン管理システムによってリビジョン ID の振り方が違うと思うので，難しそうです。パッと思いつく方法だと，リンクを貼る際には Mantis Syntax Plug-in のようなプラグインを作っておいてリンクして，旧リビジョン ID から新リビジョン ID へのマッピングを作成することでしょうか。

まとめ

システムの統合は存外簡単にできるように作られているようです。ただしある程度の計画性をもって統合しないと移行時に面倒になりそうです。

その他

最初から Trac を使えばいいじゃないという突っ込みはなしで。

捨てられたブログ