FreeBSD 障害報告の書き方

あるアプリケーションの新しいバージョンが利用可能という情報を知らせるだけの障害報告は提出しないでください。 ports のメンテナは、新しいバージョンが利用になった際には、 自動的に portscout から連絡を受けています。 もちろん port を最新版へアップデートするためのパッチの提出は歓迎されます。

メンテナンスされていない ports (MAINTAINER が ports@FreeBSD.org の ports) に対するパッチが添付されていない障害報告は、 コミッタからは取り上げられにくいものです。 メンテナンスされていない port のメンテナになるには、 リクエストの障害報告を提出してください (パッチがあることは好ましいですが、必須ではありません)。

いずれの場合も、Port 作成者のためのハンドブック で説明されている手順がもっともよい結果をもたらします (Contributing to the FreeBSD Ports Collection という文書も読んでみたいと思われるかもしれませんね)。

ベースシステムのコードで、FreeBSD への貢献者によって書かれ、維持されているもの。 たとえば、カーネル、C ライブラリやデバイスドライバ (kern に分類されているもの)、 バイナリユーティリティ (bin)、 マニュアルページや文書 (docs) やウェブページ (www) があります。 この領域のバグは全て FreeBSD 開発者に報告してください。

それ以外の人によって書かれ、維持されているベースシステムのコードで、 FreeBSD に取り込まれ、FreeBSD に合わせて変更されているもの。 たとえば、clang(1) や sendmail(8) があります。 この領域のバグのほとんどは FreeBSD 開発者に報告すべきですが、 問題が FreeBSD 特有でない場合には、 おおもとの作者に報告してください。

ベースシステムではなく FreeBSD Ports Collection (ports カテゴリ) の一部である個別のアプリケーション。 そのほとんどは FreeBSD が書いたものではありません。 FreeBSD が提供しているのは、 単なるアプリケーションをインストールする枠組みです。 したがって、問題が FreeBSD 特有であると考えられる場合にだけ FreeBSD 開発者に報告してください。 それ以外は、そのソフトウェアの開発者に連絡してください。

FreeBSD の よくある質問とその答え (FAQ) 一覧。FAQ は、ハードウェア互換性、ユーザアプリケーション や カーネルコンフィグレーション といったことに関する広い範囲の質問に対して答を示そうとしています。

メーリングリスト。 - メーリングリストを購読していなければ、 FreeBSD のウェブサイトにある アーカイブ検索を使ってください。 もし、メーリングリストで議論がされていなければ、 自分の問題についてのメッセージを送ってみて、 見落とした点を誰かが見つけてくれるかどうか、 数日間待ってみると良いでしょう。

ウェブ全体を検索する (任意)。- あなたの問題に関係する話題がないかどうかを、 お気に入りの検索エンジンを使って探してください。 あなたが知りもしなかったか、 検索しようと考えなかったメーリングリストやニュースグループのアーカイブにあたることもあるかもしれません。

次に、検索可能な FreeBSD 障害報告データベース (Bugzilla) があります。 あなたの問題が新しいものでも不明瞭でもなければ、 既に報告されている可能性がかなり高いです。

何よりもまず、 元となるソースコード内のドキュメントで、 あなたの問題が触れられていないどうかを調べてみてください。

"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-questions で議論した方がよいでしょう。

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

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

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

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

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

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

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

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

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

提出した障害報告に関連する FreeBSD のメーリングリストを ハンドブックのメーリングリスト で探し、 そのメーリングリストに手助けやコメントをお願いするメールを送ってください。

関連する IRC チャネルに参加してください。 不完全ですが一覧が https://wiki.freebsd.org/IrcChannels にあります。 チャネルにいるメンバーに提出した障害報告のことを伝えて、 助けを求めてください。 助けを求めた後は、 世界中の異なるタイムゾーンの人々がそれを取り上げることができるように、 我慢強くそのチャネルに留まってください。

報告した障害報告に興味を持つコミッタを探してください。 問題が、特定のツール、バイナリ、port、 文書もしくはソースファイルに関するものであれば、SVN リポジトリ を確認してください。 ファイルに最近変更を加えたコミッタを突き止め、 IRC もしくは電子メールで連絡をとってください。 コミッタとメールアドレスの一覧は、FreeBSD への貢献者 文書にあります。

How to Report Bugs Effectively (日本語訳) - Simon G. Tatham 氏による、(FreeBSD に限らない) 役に立つ障害報告の作成についてのすぐれたエッセイ。

Problem Report Handling Guidelines - 障害報告が FreeBSD の開発者によってどのように扱われるかについて 有益な見識をまとめた記事。