FreeBSD 障害報告の書き方

Dag-Erling Sm�rgrav

Mark Linimon

$FreeBSD: head/ja_JP.eucJP/articles/problem-reports/article.xml 40570 2013-01-12 13:49:24Z ryusuke $

$FreeBSD: head/ja_JP.eucJP/articles/problem-reports/article.xml 40570 2013-01-12 13:49:24Z ryusuke $

FreeBSD は The FreeBSD Foundation の登録商標です。

IBM, AIX, EtherJet, Netfinity, OS/2, PowerPC, PS/2, S/390 および ThinkPad は アメリカ合衆国および/またはその他の国における International Business Machines Corporation の商標です。

Intel, Celeron, EtherExpress, i386, i486, Itanium, Pentium および Xeon はアメリカ合衆国およびその他の国における Intel Corporation またはその関連会社の商標または登録商標です。

Sparc, Sparc64, SPARCEngine および UltraSPARC はアメリカ合衆国およびその他の国における SPARC International, Inc. の商標です。SPARC の商標をつけた製品は Sun Microsystems, Inc. が開発したアーキテクチャに基づいています。

Sun, Sun Microsystems, Java, Java Virtual Machine, JavaServer Pages, JDK, JSP, JVM, Netra, Solaris, StarOffice, Sun Blade, Sun Enterprise, Sun Fire, SunOS および Ultra は アメリカ合衆国およびその他の国における Sun Microsystems, Inc. の 商標または登録商標です。

製造者および販売者が製品を区別するのに 用いている表示の多くは、商標とされています。 この文書に登場する表示のうち FreeBSD Project がその商標を確認しているものには、その表示に続いて “™” または “�” 記号がおかれています。

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

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

1. はじめに

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

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

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

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

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

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

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

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

バグではないものに関する障害報告を提出することが適切と考えられるのは、 以下のような場合です。

再現することができないバグは、めったに直すことができません。 もし、バグが一度だけ発生してそれが再現できないもので、 なおかつ他の人のシステムでも起こらないようであれば、 開発者がそれを再現できる可能性も、 何が悪いのかわかる可能性もありません。 これはバグが起こらなかったことを意味するわけではありません。 しかし、このような状況ではあなたの障害報告がバグの修正に つながる見込みは非常に薄いものです。 おまけに、この手のバグは実際は故障したハードディスクや過熱した CPU が原因で起きていることが多いのです (障害報告を提出する前には必ず、可能なら、 こうした原因を排除するよう努めるべきです)。

次に、誰に障害報告を提出するか決めます。 そのためには、FreeBSD を構成するソフトウェアがさまざまな要素で構成されていることを知っておく必要があります。

それから、問題が時宜を得たものか確認すべきです。 既に修正したバグに関する障害報告を受けとることほど開発者を悩ませるものはまずありません。

ベースシステムの問題で、FreeBSD のバージョンについてよく分かっていないなら、まず FAQ の FreeBSD バージョンに関する節を読んでください。 FreeBSD では、 ベースシステムのいくつかの最新ブランチ以外は修正できません。 そのため、古いバージョンについて障害報告を提出しても、 開発者から問題がまだ起きるか確認するために、 サポートされているバージョンにアップグレードするように勧められるだけかもしれません。 セキュリティオフィサチームが、 サポートされているバージョンの一覧 を管理しています。

ある port に問題がある場合、まずはじめに Ports Collection の最新版にアップグレードして、まだ問題があるか見てください。 これらのアプリケーションは速いペースで変更されるため、 FreeBSD で完全な最新版以外に対応するのは不可能です。 アプリケーションの古いバージョンにある問題は、 直しようがありません。

3. 準備

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

4. 障害報告の書き方

問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したら、 実際に障害報告を執筆する時です。 障害報告を作成して送信するプログラムの仕組みに入る前に、 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。

4.1. よい障害報告を書くこつ

  • “Synopsis”(概要) 行を空のままにしないでください。 障害報告は、世界中に配布されるメーリングリストに送られる (そこでは、“Synopsis” (概要) は Subject: 行に使われます) と共に、 データベースにも入れられます。後でデータベースを synopsis (概要) で参照する人は、題がついていない障害報告は単に無視することでしょう。 このデータベースに登録された障害報告は、 誰かが対応済にするまでは残っていることを忘れないでください。 内容不明のものは大抵雑音に埋もれてしまいます。

  • わかりにくい“Synopsis” (概要) 行は避けましょう。 あなたが提出した障害報告を読む人がどういう状況か分かっていると仮定すべきではありません。 できるだけ詳しく書きましょう。 たとえば、その問題はシステムのどの部分にあてはまるのでしょうか。 インストール中にしか問題に当たらないのか、それとも稼働中に当たるのか。 具体的な例でいうなら、 Synopsis: portupgrade is broken (概要: portupgrade がおかしい) ではなく、 次のように書いたらどれだけ伝わりやすいか考えてみてください。 Synopsis: port ports-mgmt/portupgrade coredumps on -current (概要: sysutils/portupgrade port が -current でコアダンプします)。(ports の場合は、 “Synopsis” (概要) 行に分類と名前を入れると、 とても助かります)。

  • パッチがあるなら、そう書いてください。 パッチがついている障害報告は、 ついていないものよりも見てもらえる可能性が高いです。パッチをつける場合は、 “Synopsis” (概要) 行の先頭に [patch] という文字列 (角括弧を含みます) をいれて下さい。 (この通り書かなければならないというわけではありませんが、 慣習としてこの文字列が用いられています)。

  • あなたがメンテナなら、そう書いてください。 ソースコードの一部 (たとえば、ある port) をメンテナンスしているなら、概要行の先頭に [maintainer update] という文字列 (角括弧を含みます) をできればいれて、障害報告の “Class” を必ず maintainer-update にしてください。こうすれば、committer がその障害報告を扱う際に、いちいち確認する必要がありません。

  • 具体的に書いてください。 あなたが抱えている問題について多くの情報を出すほど、 回答してもらえる可能性は高くなります。

    • FreeBSD のバージョン (これを記載する場所があります。後述します) と、どのアーキテクチャで動かしているのかを書いてください。 動かしているのが (CDROM から、またはダウンロードして入れた) リリースでなのか、それとも Subversion でメンテナンスしているシステムでなのか (そうだとしたら、最後に更新したのはいつか) も書いてください。あなたが FreeBSD-CURRENT ブランチを追いかけていたら、それを真っ先に聞かれるでしょう。 なぜなら、FreeBSD-CURRENT では (注目を浴びる問題は特に) 修正がすぐに入る傾向があり、FreeBSD-CURRENT のユーザはそれについて行くことが求められているからです。

    • make.conf に、どのグローバルオプションを指定したか書いてください。 注意: gcc(1) に -O2 以上を設定するのは、多くの場合にバグがあることが分かっています。 FreeBSD 開発者はパッチを受け取るでしょうが、 単純に時間とボランティアが少ないため、 そのような問題は通常調査したがらず、 ただ対応していないだけだと答える可能性があります。

    • 問題が容易に再現できるようであれば、 開発者が自身で再現できるように情報を含めてください。 もし、特別な入力が行われた時に問題が起きるようであれば、 可能であれば、その入力例を入れてください。また、 実際の出力や予想される出力も含めてください。 もし、データが大きかったり、公開できないものであれば、 同じ問題を表わすような最小限のファイルを作成し、 障害報告に含めてください。

    • カーネルの問題なら、 次の情報を渡せるようにしておいてください (はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、 関係があると思う部分の抜粋は入れるべきです)。

      • カーネルコンフィグレーション (どのハードウェアデバイスがインストールされているかも含む)

      • (WITNESS などの) デバッグオプションを有効にしているか、 しているなら、 そのオプションを変更しても問題は変わらないか

      • もし生成しているなら、バックトレース、 パニックや他のコンソールの出力、または、/var /log/messages のすべてのテキスト

      • 問題がハードウェアのある部分に関連するのであれば、 pciconf -l および dmesg 出力の関連する部分

      • src/UPDATING は読んだか、そこにあなたの問題が挙がっていないか (間違いなく聞かれます)

      • 代替として動かせるカーネルが他にないか (これは、故障したディスクや過熱した CPU などのハードウェアに関連した問題で、 カーネルの問題に見えるものを除外するためです)

    • Ports の問題であれば、 次の情報を渡せるようにしておいてください (はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、 関係があると思う部分の抜粋は入れるべきです)。

      • どの ports をインストールしたのか

      • PORTSDIR など、bsd.port.mk のデフォルトを上書きする環境変数すべて

      • ports/UPDATING は読んだか、そこにあなたの問題が挙がっていないか (間違いなく聞かれます)

  • 漠然と機能を要求するのはやめましょう。 “誰かこういうことするものを実装すべきだ” という形の障害報告は、詳細な要望に比べて成果を得にくいものです。 ソースコードは誰でも利用できるのですから、何か機能が欲しければ、 それをいれる最善の手段は作業にとりかかることです。 また上述したように、こういうことは多くの場合、 障害報告データベースに登録するよりも freebsd-questions で議論した方がよいでしょう。

  • 誰かが既に似たような障害報告を提出していないか確認してください。 これは、既に述べたことではありますが、ここで繰り返しておくに値するでしょう。 Web ベースの検索エンジン http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query で調べるのは 1, 2 分程度しかかかりません。 (もちろん、誰もがときどきこれを忘れてしまうという罪を犯しています)。

  • ひとつの障害報告にはひとつの問題を報告してください。 2 つ以上の問題は、関係がなければ同じ障害報告に含めないでください。 パッチを提出する際には、一つの障害報告に複数の機能や複数のバグを、 それらが極めて関係してなければ、含めることは避けてください。 そのような障害報告は、解決するのにより多くの時間がかかります。

  • 異論のある要望は出さないようにしましょう。 あなたの障害報告がかつて論争になった分野に関するものであったら、 パッチを提出するだけでなく、そのパッチが “正当なものである” 根拠も提出したほうがよいかもしれません。 どの場合でも上述のように http://www.FreeBSD.org/search/search.html#mailinglists でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。

  • 礼儀正しくしましょう。 あなたの障害報告について作業する人は、 ほとんど全員がボランティアです。 金銭的収入以外の動機から行なっていることを、 やれと命令されるのは誰も好きではありません。 オープンソースプロジェクトに関しては、 これを常に念頭においておくとよいでしょう。

4.2. 始める前に

send-pr(1) プログラムを使うなら、環境変数 VISUAL (もし VISUAL が設定されていなければ EDITOR) が意味のあるものに設定されているか確認しましょう。

また、メール配送ソフトウェアが正常に動作することも確認してください。 send-pr(1) は障害報告の提出と追跡にメールを利用します。 send-pr(1) を動かすマシンからメールを送ることができないと、 あなたの障害報告は GNATS データベースに届きません。 FreeBSD におけるメールの設定の詳細については FreeBSD ハンドブックの “電子メール” の章 ../../../../doc/ja_JP.eucJP/books/handbook/mail.html をご覧ください。

あなたが使っているメーラが GNATS に送るメッセージに手を加えないことを確かめておいてください。 特に、メーラが自動で改行したり、タブをスペースに変更したり、 改行文字をエスケープしたりすると、 提出したパッチは使えないものになってしまいます。 もっとも、テキスト部については障害報告を web で表示した時に読みやすいように、 70 文字前後で改行を入れることをお願いしています。

send-pr(1) の代わりに web ベースの障害報告提出フォーム を利用する場合も、同様の配慮が必要です。 カットアンドペースト操作はテキストをフォーマットするのに副作用がある場合があるので気をつけてください。 場合によっては、パッチが変更されずに届くように、uuencode(1) を使わなければならないかもしれません。

最後に、提出物が長くなってしまうなら、 提出時に問題が起きて失われてしまうことのないように、 オフラインで準備しておきましょう。 これは特に web フォーム で問題になります。

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

以下は、障害報告を電子メールで提出する場合にあてはまります。

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

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

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

パッチは context 形式か unified 形式の差分を diff(1) の -c か -u オプションを使って作成してください (unified 形式の方が好まれます)。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルの正確な SVN のリビジョン番号が特定できるか確認してください。 カーネルやベースのユーティリティに関しては、新しいコードはすべて FreeBSD-CURRENT (SVN の HEAD ブランチ) でテストするべきなので、それに対するパッチが望ましいです。 適切か十分なテストが行なわれたら、そのコードは FreeBSD-STABLE ブランチにマージまたは移植されます。

パッチを添付するのではなく本文中に含める場合、 もっともありがちな問題は、 電子メールプログラムによってはタブをスペースに変更してしまい、 Makefile に含めるつもりだったものを台無しにしてしまうことです。

パッチを Content-Transfer-Encoding: quoted-printable を利用した添付ファイルとして送らないようにしてください。 これは文字をエスケープしてしまい、 パッチ全体が使い物にならなくなります。

また、障害報告の中に小さなパッチを含めるのは (とりわけ説明されている障害を修正する場合は) 大抵問題ないのですが、 大規模なパッチや新しいコードの場合は十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、その URL を障害報告に書くようにしてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり (とりわけ GNATS が処理に関わるときはそうなります)、 パッチが大きいほど興味をもった人がつなぎ直すのが面倒になります。 また、Web にパッチをおけば、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくても変更できます。 最後に、大きなパッチはデータベースのサイズをとにかく増やしてしまいます。 閉じられた障害報告は実際に消されることはなく、 保持されたまま closed という印をつけられるだけだからです。

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

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

次の節は電子メール方式にのみあてはまります。

send-pr(1) を動かすとテンプレートが表示されます。 テンプレートは特定の項目から成り立っており、 その一部にはあらかじめ埋められていたり、 その項目の目的の解説やそこに記入できる値の一覧が記載されていたりします。 コメントの部分は、自分で変更・削除しなくても、 自動的に削除されますので心配する必要はありません。

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

電子メールの雛型には、次の 2 つの一行フィールドがあります。

訳注: フィールドの意味が分かり易いように フィールド名を訳していますが、 フィールドの値も含めて 実際のフィールド名は英文字でなければなりません。

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

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

次の節では、電子メールインタフェースと web インタフェース の両方に共通なフィールドについて説明します。

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

    注意: 指定した電子メールアドレスは公開情報となり、 スパマーに利用されるかもしれません。 スパム対策を使えるようにしておくか、 一時的なメールアカウントを利用してください。 しかし、あなたが有効な電子メールアドレスを書かないと、 わたしたちはあなたの障害報告に対して質問できなくなります。

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

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

  • Organization (所属組織): あなたの好きなようにしてください。 このフィールドは何らかの深い意味で使われることはありません。

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

    上述したように、障害報告にパッチが含まれているなら、 概要の先頭に [patch] (角括弧を含みます) と書いて下さい。 Ports に関する障害報告で、あなたがメンテナなら、 [maintainer update] (角括弧を含みます) を追加して、 障害報告の “Class” を maintainer-update にするようにしてください。

  • Severity (重要度): non-critical (重要ではない)、 serious (重要)、 critical (致命的) のどれかです。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的 (たとえば、 データが壊れたり、-CURRENT で以前に比べて機能が大きく退化したなど) でない場合は、 critical に分類するのを、また多くの人に影響する (カーネルがパニックしたりフリーズする、 または特定のデバイスドライバやシステムユーティリティに問題がある) のでなければ、serious に分類するのを控えてください。 まったく同じことをやった人があまりに多いため、 問題の重要性を水増ししても、必ずしも FreeBSD 開発者がその問題に早くとりかかるわけではありません。 — 実際、 それが理由でこのフィールドにほとんど注意を払わない開発者もいます。

    注意: GNATS の情報はすべて公開されているので、 重要なセキュリティ上の問題は GNATS に提出するべきではありません。 そのような問題は、 セキュリティレポートガイドライン にしたがって送ってください。

  • Priority (優先順位): low (低い)、 medium (中間)、 high (高い) のどれかです。 high (高い) は実質的にすべての FreeBSD ユーザに影響するもの、 medium (中間) は多くのユーザに影響するものに限定すべきです。

    注意: このフィールドはあまりにも乱用されたため、 いまやほとんど意味がなくなってしまいました。

  • Category (分類): 適切な分類を選んでください。

    まず最初に行わなければならないのは、 あなたの問題がシステムのどの部分に関連しているかを決めることです。 FreeBSD は完全なオペレーティングシステムなので、 カーネル、標準ライブラリの両方、および、 周辺ドライバ、多くのユーティリティ (“ベースシステム”) をインストールします。 さらに、Ports Collection には数多くの追加のアプリケーションが用意されています。 そのため、最初に判断しなくてならないのは、 問題がベースシステムに関連しているのか、 それとも Ports Collection からインストールされた何かに関係しているのか、 ということになります。

    以下はメジャーなカテゴリについての説明です。

    • もし、問題がカーネル、(標準 C ライブラリ libc) ライブラリ、またはベースシステムの周辺ドライバで起こるのであれば、 通常は kern カテゴリを使うとよいでしょう (下記に説明するようにいくつかの例外があります)。 一般的に、マニュアルページのセクション 2, 3 もしくは 4 に書かれているようなものがここに分類されます。

    • 問題が sh(1) や mount(8) のようなバイナリプログラムで起きるのであれば、 まず最初に、それらのプログラムがベースシステムのものか、 もしくは Ports Collection から追加されたものなのかを判断してください。 よくわかならければ、 whereis programname と実行してください。 FreeBSD の Ports Collection の慣例では、 (システム管理者は、この設定を変更することができますが) すべてのものは /usr/local 以下にインストールされます。 このような場合は、ports カテゴリを使うことになります (もし、その port のカテゴリが www であっても当てはまります。説明が下にあります)。 もし、コマンドの場所が /bin, /usr/bin, /sbin もしくは /usr/sbin であれば、 それはベースシステムの一部ですので、 bin カテゴリを使ってください (gcc(1) のようないくつかのプログラムでは、gnu カテゴリを使うことになりますが、今の時点では気にしないでください)。 このカテゴリには、マニュアルページのセクション 1 または 8 に記述されているすべてが分類されます。

    • もし、エラーがスタートアップ (rc) スクリプトで起きている、または他の非実行形式の設定ファイルに関連したようなものあれば、 conf (configuration) が適切なカテゴリでしょう。 マニュアルページのセクション 5 に書かれている内容がここに分類されます。

    • 問題がドキュメント (article, book もしくはマニュアルページ) に関連したものであれば、docs が適切なカテゴリです。

    • 問題が FreeBSD ウェブページ に関連したものであれば、www を選択してください。

      注意: もし、問題が www/someportname という名前の port に関連したものであっても、 ports カテゴリを選択してください。

    さらにいくつかの特別なカテゴリがあります。

    • 問題が kern に分類されるようなものでも、 USB サブシステムに関連したものであれば、usb が適切なカテゴリです。

    • 問題が kern に分類されるようなものでも、 スレッドのライブラリに関連したものであれば、threads が適切なカテゴリです。

    • 問題がベースシステムに分類されるようなものでも、 POSIX® のような標準への準拠に関連したものであれば、 standards が適切なカテゴリです。

    その他の問題については、以下のカテゴリを使用してください。

    • 問題が、あなたの使っているプロセッサアーキテクチャでのみ起こると確信できるのであれば、 アーキテクチャ固有のカテゴリから選んでください。 良く使われている 32-bit モードの Intel 互換コンピュータは i386, 64-bit モードで動作する AMD マシンの場合は amd64 (この分類には、EMT64 モードで動作する Intel 互換のコンピュータも含まれます) を選択してください。 通常はあまりよく使われないアーキテクチャには、 arm, ia64, powerpc および sparc64 があります。

      注意: これらのカテゴリは、“よくわからない” 問題に対して間違ってよく使われます。 とりあえず推測で選んでしまうのではなく、そのような場合には misc を選んでください。

      例 1. アーキテクチャカテゴリの正しい使い方

      あなたは一般的な PC アーキテクチャのマシンを持っていて、 特定のチップセットや特定のマザーボードの問題にぶつかったようです。 この場合は、i386 がふさわしい分類になります。

      例 2. アーキテクチャカテゴリの正しくない使い方

      例: 一般的なバス用の追加の周辺カードや、 特定の種類のハードディスクドライブで問題があります。 この場合は、複数のアーキテクチャに影響する可能性があり、 kern がふさわしい分類になります。

    • もし、問題をどの分類に分ければよいのかわからなければ (上で説明したものに当てはまらなければ)、 misc カテゴリを選んでください。 このカテゴリを選択する前に、まず最初に FreeBSD general questions メーリングリスト で、 助けを求めてみてください。 存在するカテゴリの中から本当に選択すべきものをアドバイスされるかもしれません。

    以下に現在の分類一覧を示します ( http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories からもってきています)。

    • advocacy: FreeBSD の世間的なイメージに関する問題。 もはや用いられません。

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

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

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

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

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

    • gnu: gcc(1) や grep(1) などの、取り込まれた GNU ソフトウェアに関する問題。

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

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

    • java: Java™ 仮想マシンに関する問題。

    • kern: カーネル、(特定のプラットフォーム用ではない) デバイスドライバや、 ベースシステムのライブラリにに関する問題。

    • misc: これらの分類に適合しないその他の分類。(なお、 本当にここに分類されるべきものは、 リリースおよびビルドのための基盤をのぞけば、 ほとんどありません。HEAD における一時的なビルドの失敗はここに分類すべきではありません。 また、ここに分類すると見失われやすいです)。

    • ports: Ports Collection に関する問題。

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

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

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

    • threads: FreeBSD のスレッド実装 (特に FreeBSD-CURRENT 上のもの) に関する問題。

    • usb: FreeBSD の USB 実装に関する問題。

    • 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.5. 障害報告を送信する

send-pr(1) を使っている場合

テンプレートを埋め、保存してエディタを終了すると、 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

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

Web フォーム を使っている場合

submit を押す前に、 そのページに画像で表示されているテキストをフィールドに記入しなければなりません。 この不幸な手順は自動化されたシステムや、 誤りを教えられた人たちによる誤用があったために導入されました。 これは、誰もが嫌う必要悪なのです。 お願いですから、これを取り除くように要望しないでください。

なお、submit を押す前に、 どこかにあなたが書いた内容を保存しておくことを 強く奨めます。 ユーザがよく出くわす問題に、web ブラウザが、 キャッシュから無効になった画像を表示してしまうというものがあります。 あなたがそういう目に遭ってしまったら、 あなたの報告は拒否されてしまい、 書いたものを失ってしまうでしょう。

何らかの理由で画像が見られず、また send-pr(1) も使えない場合は、ご迷惑をおかけして大変申し訳ありませんが、 障害報告を bugbuster チームに 宛で送ってください。

5. フォローアップ

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

誰かがあなたに追加情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 次の 2 つの方法のどちらかで、フォローアップを提出してください。

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

6. 問題が起きたら

ほとんどの障害報告はシステムで処理され、 ただちに受け付けられます。しかし、GNATS の処理が遅れて、 10 分以上確認の電子メールが届かないこともあります。 しばらくお待ちください。

さらに、GNATS は入力をすべて電子メールで受け取るので、 FreeBSD が渡されたメールをすべて spam フィルタに通しても影響が出ます。 1, 2 時間で返答を受け取っていなければ、 spam フィルタに引っかかった可能性があります。 その場合は、 にメールを送って GNATS 管理者の助力をもとめてください。

注意: spam の判断基準に、(障害報告に HTML をいれる必要はないにもかかわらず) spam によくみられる HTML メールであるかどうか見るというものがあります。 障害報告を送る際には、HTML メールにしないことを強く推奨します。 フィルタにひっかかる可能性が高いだけでなく、 データベースをごちゃごちゃにしてしまうだけという可能性が高いからです。 昔ながらのテキストメールの方がずっとよいでしょう。

まれに、障害報告が受け付けられ、追跡番号が付いたのに、 web の検索ページのどの一覧にも表示されないことがあります。 その場合、おそらくデータベースの索引がデータベースそのものと 同期が外れてしまったのだと思われます。 本当にそうか確認する方法は、 特定の障害報告を見るページにいって、 障害報告が出てくるか確認することです。 障害報告が存在するなら、 にメールを出して GNATS 管理者に知らせてください。 ただし、定期的にデータベースを再構築する cron ジョブが走っていますので、急いでいるのでなければ、 特になにもする必要はありません。

7. さらなる読みもの

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

本文書、および他の文書は ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/ からダウンロードできます。

FreeBSD に関する質問がある場合には、ドキュメント を読んだ上で <questions@FreeBSD.org> まで (英語で) 連絡してください。
本文書に関する質問については、<doc@FreeBSD.org> まで電子メールを (英語で) 送ってください。