問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したら、 実際に障害報告を執筆する時です。 障害報告を作成して送信するプログラムの仕組みに入る前に、 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。
“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 でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。
礼儀正しくしましょう。 あなたの障害報告について作業する人は、 ほとんど全員がボランティアです。 金銭的収入以外の動機から行なっていることを、 やれと命令されるのは誰も好きではありません。 オープンソースプロジェクトに関しては、 これを常に念頭においておくとよいでしょう。
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 フォーム で問題になります。
以下は、障害報告を電子メールで提出する場合にあてはまります。
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 という印をつけられるだけだからです。
また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件の ライセンス下にあるものと仮定されることに留意しておくべきです。
次の節は電子メール方式にのみあてはまります。
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 <[email protected]>
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 を選んでください。
もし、問題をどの分類に分ければよいのかわからなければ (上で説明したものに当てはまらなければ)、 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: マニュアルページ、オンライン文書に関する問題。
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: できればパッチか、少なくとも回避方法を記述する (同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません) べきですが、 はっきりとしたアイデアがなければ開発者が思索をめぐらすために、 このフィールドは空にしておけば良いでしょう。
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 チームに <[email protected]>
宛で送ってください。
本文書、および他の文書は ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/ からダウンロードできます。
FreeBSD に関する質問がある場合には、ドキュメント を読んだ上で <[email protected]> まで (英語で)
連絡してください。
本文書に関する質問については、<[email protected]> まで電子メールを (英語で)
送ってください。