あなたは一般的な PC アーキテクチャのマシンを持っていて、 特定のチップセットや特定のマザーボードの問題にぶつかったようです。 この場合は、i386
がふさわしい分類になります。
サポートされているバージョンの一覧 を管理しています。
ある port に問題がある場合、 開発元にバグを報告することを考えて見てください。 すべてのソフトウェアのすべてのバグに対し、FreeBSD プロジェクトが修正することは不可能です。
従うべき良い規則は、 障害報告を提出する前に常に問題の背景を調べることです。 あなたの問題はすでに報告されているかもしれません。 また、メーリングリストで議論されている最中か、 最近議論されていたかもしれません。 あなたが動かしているものより新しいバージョンで、 既に修正済みということすらありえます。 ですから、障害報告を提出する前に自明な場をすべて確認すべきです。 FreeBSD では、以下になります。
FreeBSD の よくある質問とその答え (FAQ) 一覧。FAQ は、ハードウェア互換性、ユーザアプリケーション や カーネルコンフィグレーション といったことに関する広い範囲の質問に対して答を示そうとしています。
メーリングリスト。 - メーリングリストを購読していなければ、 FreeBSD のウェブサイトにある アーカイブ検索を使ってください。 もし、メーリングリストで議論がされていなければ、 自分の問題についてのメッセージを送ってみて、 見落とした点を誰かが見つけてくれるかどうか、 数日間待ってみると良いでしょう。
ウェブ全体を検索する (任意)。- あなたの問題に関係する話題がないかどうかを、 お気に入りの検索エンジンを使って探してください。 あなたが知りもしなかったか、 検索しようと考えなかったメーリングリストやニュースグループのアーカイブにあたることもあるかもしれません。
次に、検索可能な FreeBSD 障害報告データベース (Bugzilla) があります。 あなたの問題が新しいものでも不明瞭でもなければ、 既に報告されている可能性がかなり高いです。
何よりもまず、 元となるソースコード内のドキュメントで、 あなたの問題が触れられていないどうかを調べてみてください。
FreeBSD の基本部分のコードについては、 システムの /usr/src/UPDATING の内容か、https://svnweb.freebsd.org/base/head/UPDATING?view=log にある最新版をよく調べるべきです (あるバージョンから別のバージョンにアップグレードしようとしているのであれば -特に -current
ブランチに上げようとしているなら、 これは非常に重要な情報です)。
しかし、問題が FreeBSD Ports Collection からインストールされたものにあるのであれば、 /usr/ports/UPDATING (個別の ports) または /usr/ports/CHANGES (Ports Collection 全体に影響する変更) を参照すべきです。https://svnweb.freebsd.org/ports/head/UPDATING?view=log と https://svnweb.freebsd.org/ports/head/CHANGES?view=log は svnweb からも参照できます。
問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したら、 実際に障害報告を執筆する時です。 障害報告を作成して送信するプログラムの仕組みに入る前に、 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。
"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/#mailinglists でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。
礼儀正しくしましょう。 あなたの障害報告について作業する人は、 ほとんど全員がボランティアです。 金銭的収入以外の動機から行なっていることを、 やれと命令されるのは誰も好きではありません。 オープンソースプロジェクトに関しては、 これを常に念頭においておくとよいでしょう。
web ベースの障害報告提出フォーム を利用する場合も、同様の配慮が必要です。 カットアンドペーストを行う場合には、 ホワイトスペースやその他のテキストフォーマットを変えてしまう可能性があるので、気をつけてください。
最後に、提出物が長くなってしまうなら、 提出時に問題が起きて失われてしまうことのないように、 オフラインで準備しておきましょう。
パッチを添付する場合、 unified 形式の差分を svn diff
または diff(1) の -u
オプションを使って作成してください。 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルに対するリポジトリの SVN のリビジョン番号が特定できることを確認してください。 カーネルやベースのユーティリティに関しては、新しいコードはすべて FreeBSD-CURRENT (SVN の HEAD ブランチ) でテストするべきなので、それに対するパッチが望ましいです。 適切か十分なテストが行なわれたら、そのコードは FreeBSD-STABLE ブランチにマージまたは移植されます。
パッチを添付するのではなく本文中に含める場合、 もっともありがちな問題は、 電子メールプログラムによってはタブをスペースに変更してしまい、 Makefile に含めるつもりだったものを台無しにしてしまうことです。
パッチを Content-Transfer-Encoding: quoted-printable
を利用した添付ファイルとして送らないようにしてください。 これは文字をエスケープしてしまい、 パッチ全体が使い物にならなくなります。
また、障害報告の中に小さなパッチを含めるのは (とりわけ説明されている障害を修正する場合は) 大抵問題ないのですが、 大規模なパッチや新しいコードの場合は十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、 その URL を障害報告に書くようにしてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり、 パッチが大きいほど興味をもった人がつなぎ直すのが面倒になります。 また、Web にパッチをおけば、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくても変更できます。 最後に、大きなパッチはデータベースのサイズをとにかく増やしてしまいます。 閉じられた障害報告は実際に消されることはなく、 完了の状態で保持されたままになるだけだからです。
また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件のライセンス下にあるものと仮定されることに留意しておくべきです。
指定した電子メールアドレスは公開情報となり、 スパマーに利用されるかもしれません。 スパム対策を使えるようにしておくか、 一時的なメールアカウントを利用してください。 有効な電子メールアドレスを書いていただかないと、 わたしたちは障害報告に対する質問をあなたに対してできないので、 ご留意ください。 |
バグの申請には、以下のフィールドを使ってください。
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
が適切なカテゴリです。
もし、問題が |
さらにいくつかの特別なカテゴリがあります。
問題が kern
に分類されるようなものでも、 USB サブシステムに関連したものであれば、usb
が適切なカテゴリです。
問題が kern
に分類されるようなものでも、 スレッドのライブラリに関連したものであれば、threads
が適切なカテゴリです。
問題がベースシステムに分類されるようなものでも、 POSIX® のような標準への準拠に関連したものであれば、 standards
が適切なカテゴリです。
その他の問題については、以下のカテゴリを使用してください。
問題が、あなたの使っているプロセッサアーキテクチャでのみ起こると確信できるのであれば、 アーキテクチャ固有のカテゴリから選んでください。 良く使われている 32-bit モードの Intel 互換コンピュータは i386
, 64-bit モードで動作する AMD マシンの場合は amd64
(この分類には、EMT64 モードで動作する Intel 互換のコンピュータも含まれます) を選択してください。 通常はあまりよく使われないアーキテクチャには、 arm
および powerpc
があります。
これらのカテゴリは、"よくわからない" 問題に対して間違ってよく使われます。 とりあえず推測で選んでしまうのではなく、そのような場合には |
あなたは一般的な PC アーキテクチャのマシンを持っていて、 特定のチップセットや特定のマザーボードの問題にぶつかったようです。 この場合は、i386
がふさわしい分類になります。
例: 一般的なバス用の追加の周辺カードや、 特定の種類のハードディスクドライブで問題があります。 この場合は、複数のアーキテクチャに影響する可能性があり、 kern
がふさわしい分類になります。
もし、問題をどの分類に分ければよいのかわからなければ (上で説明したものに当てはまらなければ)、 misc
カテゴリを選んでください。 このカテゴリを選択する前に、まず最初に FreeBSD general questions メーリングリスト で、 助けを求めてみてください。 存在するカテゴリの中から本当に選択すべきものをアドバイスされるかもしれません。
Environment (環境): 問題が発生した環境を可能な限り正確に記述すべきです。 ここには、オペレーティングシステムのバージョン、 特定のプログラムのバージョンまたは問題があるファイル、 そしてシステムの設定などのような関係する項目、 問題に影響を及ぼすインストールしたその他のソフトウェアなどが含まれます。 - 手短にいうなら、その問題が生じる環境を再構築するために、 開発者が知らなければならないことすべてです。
Description: あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り、 推測は避けるようにしてください。 ここには、問題を再現する方法を記述してください。 回避方法をご存知でしたら、それについても記述してください。 この情報は、同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません。
障害報告を提出すると、 障害報告に割り当てられた追跡用の番号と状況を確認するために利用する URL を含む、確認のための電子メールが送られてくるでしょう。 ちょっぴり運がよければ、 誰かがあなたの問題に興味を持ってそれに取り組もうとするでしょうし、 場合によってはなぜそれが問題でないか説明してくれるでしょう。 状況に何かの変更があると、 誰かがあなたの障害報告を審査追跡状態にして、 何らかのコメントかパッチの通知を自動的に受けとるでしょう。
誰かがあなたに追加情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 フォローアップを提出してください。 バグが修正されない一番の理由は、 提出者とのコミュニケーション不足が原因です。 一番楽なのは、障害報告検索ページ から行ける、それぞれの障害報告の web ページのコメントオプションを利用することです。
問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 この障害報告は議論を終了することができます、 とコメントを送ってください。
時々、提出した障害報告が誰にも割り当てられなかったり、 コメントのない状態が 1, 2 週間続くことがあります。 障害報告のバックログが増えているときや、 休暇シーズンに起こり得ます。 提出した障害報告に注意が引かれない状況が何週間も続くようであれば、 その分野に興味を持っているコミッタを見つけると良いでしょう。
これには、幾つかの方法がありますが、以下の順番が好ましいでしょう。 それぞれのコミュニケーションチャネルへのコンタクトには数日開けてください。
提出した障害報告に関連する FreeBSD のメーリングリストを ハンドブックのメーリングリスト で探し、 そのメーリングリストに手助けやコメントをお願いするメールを送ってください。
関連する IRC チャネルに参加してください。 不完全ですが一覧が https://wiki.freebsd.org/IrcChannels にあります。 チャネルにいるメンバーに提出した障害報告のことを伝えて、 助けを求めてください。 助けを求めた後は、 世界中の異なるタイムゾーンの人々がそれを取り上げることができるように、 我慢強くそのチャネルに留まってください。
報告した障害報告に興味を持つコミッタを探してください。 問題が、特定のツール、バイナリ、port、 文書もしくはソースファイルに関するものであれば、SVN リポジトリ を確認してください。 ファイルに最近変更を加えたコミッタを突き止め、 IRC もしくは電子メールで連絡をとってください。 コミッタとメールアドレスの一覧は、FreeBSD への貢献者 文書にあります。
メンテナやユーザ同様、これらの人々もボランティアであるため、 すぐには障害報告に対応出来ないかもしれません。 フォローアップには、 我慢強くそして一貫性を持って対応することが推奨されます。 また、そのように対応すると協力を得やすいでしょう。 十分な配慮や努力をもってフォローアップに臨めば、 提出した障害報告に対応してくれるコミッタが見つかるのも時間の問題です。
バグシステムに関する問題を見つけたら、 バグとして提出してください。 まさにこの目的のためのカテゴリが用意されています。 もし障害報告の提出が難しいようであれば、バグマイスター (bugmeister@FreeBSD.org) に連絡をしてください。
完全なものとはいえませんが、 適切な障害報告の書き方と手順について関連する資料を示します。
How to Report Bugs Effectively (日本語訳) - Simon G. Tatham 氏による、(FreeBSD に限らない) 役に立つ障害報告の作成についてのすぐれたエッセイ。
Problem Report Handling Guidelines - 障害報告が FreeBSD の開発者によってどのように扱われるかについて 有益な見識をまとめた記事。