FreeBSD 障害報告の書き方

Dag-Erling Sm�rgrav

$FreeBSD: doc/ja_JP.eucJP/articles/problem-reports/article.sgml,v 1.3 2004/08/08 13:44:00 hrs Exp $

この記事では、明瞭な障害報告 (Problem Report: PR) を FreeBSD プロジェクトに提出する方法を解説します。

[ 分割版 / 単一版 ]
Table of Contents
1. はじめに
2. いつ障害報告を提出すればよいのか
3. 準備
4. 障害報告の書き方
5. フォローアップ
6. さらなる読みもの

1. はじめに

ソフトウェアの利用者が持っている 多くのいらただしい経験のうちの一つは、 “それはバグじゃない”、“ひどい障害報告だ” などのようなそっけなく理解の役に立たない説明によって、 障害報告があっさり片付けられてしまうことです。 同様に、ソフトウェア開発者が持っている 多くのいらただしい経験のうちの一つは、 実際は障害報告ではない単なるサポート要求や 何が問題でどのように再現するかについての情報が 乏しいまたは欠落している障害報告が殺到することです。

この記事のねらいは、上手な障害報告の書き方について説明することです。 上手な障害報告とはどういうものでしょうか? そうですね、単刀直入に要点を言えば、 上手な障害報告とは、迅速に解析を進め処理を行うことができ、 一度に利用者と開発者がお互いに満足できるものです。

この記事では主として FreeBSD の障害報告に焦点を絞っていますが、 他のソフトウェアプロジェクトでも多くの部分が当てはまるでしょう。

この記事はテーマ別に整理されており、順番に読めるようにはなっていません。 そのため、ステップバイステップのチュートリアルとして利用するよりも、 障害報告を提出する前に全体を通して読むとよいでしょう。

2. いつ障害報告を提出すればよいのか

問題には多くの種類がありますが、 それらすべてが障害報告に値するというわけではありません。 もちろん、誰しもが完璧ではありませんので、 実際はコマンドの構文を勘違いしていたり、 設定ファイルに書き間違いをしている場合などを プログラムにバグを見つけた! と思い込んでしまうことがあるでしょう (とは言っても、それ自身、文書が適切に記述されていなかったり、 アプリケーションのエラー処理が甘いことを暗示している可能性があります)。 それ以外にも、障害報告を提出することが正しい行動ではなく、 あなたや開発者たちをただ 不満にさせるためだけに作用してしまう場合があります (訳注: はっきりと把握していないことを報告すべきではありません。 要領を得ない障害報告は扱いにくいものです)。 逆に、バグというよりも、 何か別の報告として提出した方が適切な場合があります -- たとえば、既存機能の拡張や新しい機能の搭載要求のようなものです。

では、何がバグで何がバグでないのか、 どのようにして決めれば良いでしょうか? 簡単な経験則として、それを質問として (だいたい “どうすれば X できますか?” や “Y はどこで見つけることができますか?” のような形式で) 表現できるなら、あなたの問題はバグではありません。 いつも白黒はっきりするわけではありませんが、 この質問規則は問題の非常に多くの部分があてはまります。 もし、このような質問に対する答えを求めているのなら、 FreeBSD general questions メーリングリスト にあなたの質問を送ってみることを検討してください。

訳注: FreeBSD general questions メーリングリスト へのメールは英語でお願いします。 日本語にでの質問は、FreeBSD users-jp メーリングリスト か などに送ってください。

バグではないものに関する障害報告を 提出することが適切かもしれない条件は、以下のような時です。

もう一つ、もし、バグに遭遇したシステムが実際には最新でない場合、 システムを最新の状態にして、最新のシステムでも問題が再現するか試した後に 障害報告を提出することを真剣に考えるべきだということです。 既に修正されたバグに関する障害報告を受けとること以上に、 開発者を悩ませるものはほとんどありません。

最後に、再現することができないバグは、めったに直すことができません。 もし、バグが一度だけ発生してそれが再現できないもので、 なおかつ他の人のシステムでも起こらないようであれば、 開発者はそれを再現しようとしてもできませんし、 何が悪いのか理解する機会もありません。 これはバグが起こらなかったことを意味するわけではありません。 しかし、このような状況ではあなたの障害報告がバグの修正に つながる見込みは非常に薄く、報告をやめることを検討すべきです。

3. 準備

従うべき良い規則として、 障害報告を提出する前に常に問題の背景を調べることです。 おそらく、あなたの問題は既に報告されています。 また、メーリングリストで議論されていたり、 最近議論されていたことでしょう。 さらに、あなたが動かしているものより、 既に修正された新しいバージョンがあるかもしれません。 したがって、障害報告を提出する前に明白な部分をすべて確認すべきです。 FreeBSD では、以下のような方法があります。

次に、障害報告が適切な人物に届くことを確認する必要があります。

まず、問題がサードパーティソフトウェアのバグであれば、 原作者に報告をすべきです。 そうでなければ、FreeBSD プロジェクトに報告してください。 このルールには二つの例外があります。 一つ目は、もしバグが他のプラットフォームで発生しなければ、 FreeBSD に移植されたソフトウェアに原因が存在する場合です。 二つ目は、原作者がバグを既に修正していて そのソフトウェアの新しいバージョンかパッチを公開しているが、 FreeBSD に移植されたソフトウェアがまだ更新されていない場合です。

それから、FreeBSD のバグ追跡システムは 発信者が選択した分類に従って 障害報告を分別しているということに注意してください。 もし間違った分類を選択した場合、あなたが送った障害報告は 誰かが再分類する良い機会がくるまでしばらく見落とされるでしょう。

4. 障害報告の書き方

自分の問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したのですから、 実際に障害報告を執筆する時です。 環境変数 VISUAL (か、もし VISUAL が設定されていなければ EDITOR) が何らかの使える値に設定されているか確認して、 send-pr(1) を実行します。

4.1. パッチやファイルを添付する

send-pr(1) プログラムは、 障害報告にファイルを添付する機能を備えています。 あなたが望む数だけ、それぞれ一意の名前を持ったファイル (すなわち、パスを除いた適切な名前のファイル) を添付することができます。 コマンドラインオプション -a で 添付するファイルの名前を指定してください。

% send-pr -a /var/run/dmesg -a /tmp/errors

添付するファイルがバイナリであっても心配しないでください。 メールエージェントが混乱しないように、自動的に符合化が行われます。

パッチは context 形式か unified 形式の差分を diff(1) の -c か -u オプションを 使って作成してください。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルの正確な CVS のリビジョン番号が特定できるか 確認してください。

一般的に、 障害報告の中に小さなパッチを含める分にはいいのですが、 記載される問題についての修正が大規模な場合や新しいコードの場合は 十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、その URL を障害報告に含めてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり (とりわけ Gnats が処理に関わるときはそうです)、 肝心な部分が変にならないように注意をはらってください。 また、パッチに変更があった場合、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくとも Web から該当部分のパッチを送信して変更することができます。

また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件の ライセンス下にあるものと仮定されることに留意しておくべきです。

4.2. テンプレートに記入する

テンプレートは特定のフィールドから成り立っており、 あらかじめ書き込まれた部分がいくつかあります。そこには フィールドの目的が何かを説明する解説や そのフィールドに利用可能な値が書かれています。 コメントの部分は、自分で変更・削除しなくても、 自動的に削除されますので心配する必要はありません。

テンプレートの先頭にある SEND-PR: と書かれている行の下が電子メールのヘッダです。 通常、この部分を変更する必要はありませんが、 障害報告を送信する機械やアカウントで メールを出すことはできるが受けとることができない場合、 From: と Reply-To: に 実際のメールアドレスを設定すべきです。 また、自分 (や他の誰か) に障害報告の複製を送りたい場合は、 電子メールアドレスを Cc: ヘッダに追加してください。

次に、一連の一行フィールドが続きます。

訳注: フィールドの意味が分かり易いように フィールド名を訳していますが、 フィールドの値も含めて 実際のフィールド名は英文字である必要があります。

  • Submitter-Id (提出者-Id): これは変更しないでください。 あなたが FreeBSD-STABLE を動かしている場合でも、既定値である current-users が正しいのです。

  • Originator (あなたの名前): これは普通、現在ログインしているユーザの GECOS フィールドを使って既に埋められています。 あなたの実際の名前を指定してください。 お好みで、名前の後ろに電子メールアドレスを 山括弧 (< と > のこと) で閉じて付けることができます。

    訳注: たとえば、以下のように書くことができます。

    From: FreeBSD Taro <FreeBSD-Taro@example.org>

  • Organization (所属組織): あなたが望むのなら好きに使えます。 このフィールドは何らかの深い意味で使われることはありません。

  • Confidential (機密): これは no で既に埋められています。 機密扱いの FreeBSD 障害報告のようなものはないため、 変更することに意味はありません。-- 障害報告データベースは CVSup によって、 世界的に配布されています。

  • Synopsis (概要): 問題についての簡にして要を得た説明を書き込んでください。 概要は障害報告メールのサブジェクトとして利用されており、 一覧や要旨にも使われています。 概要が不明瞭な障害報告は無視される傾向があります。

    障害報告にパッチを添付する場合、概要の先頭に [PATCH] と書いてください。

  • Severity (重要度): non-critical (重要ではない)、 serious (重要)、 critical (致命的) のどれかです。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的 (たとえば、 root 権限を悪用できたり、 パニックを容易に再現できるなど) でない場合は、 critical に分類するのは控えてください。 障害報告を提出する人達は自分の問題を大げさに評価しがちであり、 そのため開発者はこのフィールドや次のフィールドを無視する傾向があります。

  • Priority (優先順位): low (低い)、 medium (中間)、 high (高い) のどれかです。 分類の基準は前述されてますので読んでください。

  • Category (分類): 以下から一つを選んでください:

    • advocacy: FreeBSD の一般像に関する問題。めったに使われません。

    • alpha: Alpha プラットフォーム固有の問題。

    • bin: 基本システムに含まれるユーザランドプログラムに関する問題。

    • conf: 設定ファイルや、既定値などに関する問題。

    • docs: マニュアルページ、オンライン文書に関する問題。

    • gnu: gcc(1) や grep(1) などの GNU ソフトウェアに関する問題。

    • i386: i386 プラットフォーム固有の問題。

    • ia64: ia64 プラットフォーム固有の問題。

    • java: Java™ に関する問題。

    • kern: カーネルに関する問題。

    • misc: これらの分類に適合しないその他の分類。

    • ports: ports ツリーに関する問題。

    • powerpc: PowerPC プラットフォーム固有の問題。

    • sparc64: SPARC プラットフォーム固有の問題。

    • standards: 標準規格への適合問題。

    • www: FreeBSD ウェブサイトへの変更と改善。

  • Class: 以下から一つを選んでください。

    • sw-bug: ソフトウェアのバグ。

    • doc-bug: 文書中の間違い。

    • change-request: 機能の追加や、既存の機能の変更についての要望。

    • update: ports やその他の寄贈ソフトウェアに対する更新。

    • maintainer-update: 保守者の ports に対する更新。

  • Release: あなたが動作させている FreeBSD のバージョン。 これは send-pr(1) によって自動的に書き込まれますが、 もし、あなたが障害が起きているものと違うシステムから障害報告を 送信する場合に限り変更する必要があります。

最後に、一連の複数行フィールドがあります。

  • Environment (環境): 問題が発生した環境を可能な限り正確に記述すべきです。 ここには、オペレーティングシステムのバージョン、 特定のプログラムのバージョンまたは問題があるファイル、 そしてシステムの設定などのような関係する項目、 問題に影響を及ぼすインストールしたその他の ソフトウェアなどが含まれます。-- その問題が生じる環境を再構築するために、 開発者はなんでも知る必要があります。

  • Description: あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り 推測は避けるようにしてください。

  • How-To-Repeat: 問題を再現させるために取る必要のある行動の概要。

  • Fix: できればパッチか、少なくとも回避方法を記述する (同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません) べきですが、 はっきりとしたアイデアがなければ開発者が思索をめぐらすために、 このフィールドは空にしておけば良いでしょう。

4.3. 障害報告を送信する

テンプレートを書き終えて、 保存してエディタを終了すると、send-pr(1) は s)end, e)dit or a)bort? のような 表示を出して指示を求めます。 s を押せば障害報告の提出に進めますし、 e だとエディタが再び実行されてさらに編集できます。 a なら作業を中止できます。 abort を選択した場合、いままで書いていた障害報告はディスクに残りますので (send-pr(1) は終了前にそのファイル名を示します)、 暇な時にそれを編集したり、場合によっては よりネットワーク接続性のよいシステムに持っていくことができるでしょう。 この作業ファイルは、send-pr(1) の -f オプションを使って送ることができます。

% send-pr -f ~/my-problem-report

上記の操作では、指定されたファイルを読み込み、 書式が正しいか検証し、ファイル中のコメント部分を取り除いて、 障害報告が送信されます。

5. フォローアップ

障害報告を提出すると、 障害報告に割り当てられた追跡用の番号と 状況を確認するために利用する URL を含む、 確認のための電子メールが送られてくるでしょう。 ちょっぴり運がよければ、誰かがあなたの問題に興味を持って それについて取り組もうとするでしょうし、 場合によってはなぜそれが問題でないか説明してくれるでしょう。 状況に何かの変更があると、 誰かがあなたの障害報告を審査追跡状態にして、 何らかのコメントかパッチの通知を自動的に受けとるでしょう。

誰かがあなたにさらなる情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 バグ追跡システムがどの障害報告に結びつければよいか知るために、 件名に追跡用の数字が含まれているかを確かめて にメールを送ってください。

問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 この障害報告は議論を終了することができます、と (前述の方法で) フォローアップを送ってください。

6. さらなる読みもの

適切な障害報告の書き方と手順について関連する資料を示しますが、 決して完全なものではありません。