付録E バグ報告のやり方を説明した例

以下に示すのは、Subversion プロジェクトが新しいユーザー向けに作った、 バグ報告に関する説明書をちょっと編集したものです。 こうした説明書がなぜ重要なのかについては、 8章ボランティアの管理 「すべてのユーザーの協力を得るために」 を参照してください。 オリジナルの文書は、 http://svn.collab.net/repos/svn/trunk/www/bugs.html にあります。




                    Subversion に関するバグ報告のやり方

この文書は、どこに、どうやってバグを報告すればいいかを説明したものです。(未解決のバグをすべて一覧
にしているわけではありません ー そのかわり、バグを報告する方法がわかります。)



どこにバグを報告すべきか
------------------------

    * バグが Subversion そのものに関することなら、users@subversion.tigris.org にメールを送ってく
      ださい。それがバグだと確認したら、誰かが (たぶんあなたが) バグ追跡システムに登録することができます。
      (バグであることを確信している場合は、私達の開発用メーリングリスト dev@subversion.tiglis.org
      に直接メールしてください。しかし、バグかどうか自信がない場合は、users@subversion.tigris.org
      にはじめにメールした方がよいです。なぜなら、そこにいる誰かが、あなたが遭遇した subversion の
      挙動が正しいかそうでないかを教えてくれるからです。)

    * バグが APR ライブラリに関することなら、以下のメーリングリスト両方にメールを送ってください:
      dev@apr.apache.org, dev@subversion.tigris.org

    * バグが Neon HTTPライブラリに関することなら、以下にメールを送ってください:
      neon@webdav.org, dev@subversion.tigris.org

    * バグが Apache HTTPD 2.0 に関することから、以下のメーリングリスト両方にメールを送ってください:
      dev@httpd.apache.org, dev@subversion.tigris.org
      Apache httpd 向けの開発者メーリングリストは非常にたくさんのメールが流れています。よって、あ
      なたのバグ報告のメールは見落とされるかもしれません。その場合は、バグ報告を 
      http://httpd.apache.org/bug_report.html に投稿することもできます。

    * バグが敷物(rug)の下にあったら、抱きしめて(hug)あげて、快適なもの(snug)にしましょう。



バグ報告のやり方
----------------

まず、バグかどうかを確認してください。Subversion があなたの思ったように動かないなら、ドキュメント
とメーリングリストのアーカイブを調べて、subversion があなたの思ったように動くはず、という証拠を探
してください。勿論、subversion があなたのデータを壊してしまったとか、モニターから煙が出てきた、な
ど常識の範囲であれば、あなたの判断を信じてよいでしょう。しかし、自信がないのであれば、まずはユーザ
ー向けのメーリングリスト、users@subversion.tigris.org か、irc.freenode.net の IRC チャンネル #svn
で聞いてみましょう。

いったんそれがバグだとわかったら、もっとも重要なのは、バグに関する簡単な説明と再現方法を考えること
です。たとえば、仮にバグであれば、はじめに見つけたときには5つのファイルに対して10回以上のコミット
をしていた場合、1ファイルに対して1回だけコミットして現象を再現させてみましょう。再現手順が簡単なも
のであればあるほど、開発者がバグを再現し、修正する確率が高くなります。

バグかどうかの簡易チェック: Subversion の最新バージョンを使ってますか? ホントに? :-) そ
のバグは既に修正されているかもしれませんよ。最新の Subversion 開発ツリーでもあなたのバグの再現手順
が再現できるかを確認してみましょう。

再現手順に加えて、そのバグを再現させた環境を完璧に説明する必要もあります。つまり、以下のような情報です:

    * あなたのオペレーティングシステム
    * Subversion のバージョン、かつ/または リビジョン番号
    * ビルドに使ったコンパイラと、ビルドの設定オプション
    * あなたが独自に加えたあらゆる変更
    * もしあれば、一緒に使っている Barkley DB のバージョン
    * 関連がありそうなその他全ての情報。できるだけ多くの情報を含んだエラー情報。

この情報が全て揃えば、バグレポートを書く準備ができました。どんなバグであるかの説明をわかりやすく書
くことから始めましょう。つまり、Subversion がどう動いてほしいのか、それに対して実際はどう動いてい
るのかを書きましょう。あなたにとっては明らかにバグであっても、他の人にとってはそうでないかもしれま
せん。よって、推測ゲームになるのを避けるのがベストです。次に再現した環境に関する説明をして、再現手
順を書きます。バグの原因に関する考察や、それを修正するためのプログラムを含めたいのなら、それは素晴
らしい! 修正プログラムの送り方を http://subversion.apache.org/docs/community-guide/#patches 
で見てください。

これら全ての情報を dev@subversion.tigris.org に投稿しましょう。もしあなたが既にそうしているか、バ
グ追跡システムに登録するように頼まれたのなら、バグ追跡システムのページに行き、そこの指示に従ってく
ださい。

ここまで読んでくれてありがとう。優れたバグ報告を行うには、たくさんの努力が必要なのはわかっています。
しかし、優れた報告は開発者の時間を多く節約でき、バグが修正される確率を一層高めるものなのです。