4. 障害報告の書き方

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

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

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

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

  • パッチがあるなら、そう書いてください。 パッチがついている障害報告は、 ついていないものよりも見てもらえる可能性が高いです。 Bugzilla の Keyword で patch を選択してください。

  • あなたがメンテナなら、そう書いてください。 ソースコードの一部 (たとえば、ある port) をメンテナンスしているなら、障害報告の Class を必ず maintainer-update にしてください。こうすれば、committer がその障害報告を扱う際に、いちいち確認する必要がありません。

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

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

    • make.conf, src.conf, および src-env.conf に、指定したグローバルオプションの情報を記述してください。 数多くのオプションを設定できるため、 すべての組み合わせについて、 完全に対応しているわけではありません。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

4.2. 始める前に

web ベースの障害報告提出フォーム を利用する場合も、同様の配慮が必要です。 カットアンドペーストを行う場合には、 ホワイトスペースやその他のテキストフォーマットを変えてしまう可能性があるので、気をつけてください。

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

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

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

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

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

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

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

4.4. フォームを記入する

注記:

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

バグの申請には、以下のフィールドを使ってください。

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

  • Severity (重要度): Affects only me, Affects some people および Affects many people のどれかを選択してください。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的でない場合は、 Affects many people に分類するのを控えてください。 まったく同じことをやる人があまりに多いため、 問題の重要性を水増ししても、必ずしも FreeBSD 開発者がその問題に早くとりかかるわけではありません。

  • 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 カテゴリを使ってください。 このカテゴリには、マニュアルページのセクション 1 または 8 に記述されているすべてが分類されます。

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

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

      注記:

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

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

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

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

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

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

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

      注記:

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

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

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


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

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


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

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

  • Description: あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り、 推測は避けるようにしてください。 ここには、問題を再現する方法を記述してください。 回避方法をご存知でしたら、それについても記述してください。 この情報は、同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません。

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

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

本文書に関する質問については、 <doc@FreeBSD.org> まで電子メールを (英語で) 送ってください。