FreeBSD 障害報告の書き方

Smørgrav Dag-Erling [FAMILY Given]

寄稿:

Linimon Mark [FAMILY Given]

改訂: 48562

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

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

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

SPARC, SPARC64 および UltraSPARC はアメリカ合衆国およびその他の国における SPARC International, Inc. の商標です。 SPARC International, Inc は、すべての SPARC 商標を所有しています。 また、ライセンス許諾契約のもとで、 そのメンバーは、これらの商標を適切な範囲で使用することができます。

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

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

2016-04-11 08:24:05Z : ryusuke.
概要

この記事では、明瞭な障害報告 (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 メーリングリスト などに送ってください。

ports または FreeBSD の一部ではない他のソフトウェアに関する障害報告を提出する際には、 以下に注意してください。

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

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

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

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

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

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

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

3. 準備

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

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

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

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

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

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

    FreeBSD の基本部分のコードについては、 システムの /usr/src/UPDATING の内容か、http://svnweb.freebsd.org/base/head/UPDATING?view=log にある最新版をよく調べるべきです (あるバージョンから別のバージョンにアップグレードしようとしているのであれば ―特に -current ブランチに上げようとしているなら、 これは非常に重要な情報です)。

    しかし、問題が FreeBSD Ports Collection からインストールされたものにあるのであれば、 /usr/ports/UPDATING (個別の ports) または /usr/ports/CHANGES (Ports Collection 全体に影響する変更) を参照すべきです。http://svnweb.freebsd.org/ports/head/UPDATING?view=loghttp://svnweb.freebsd.org/ports/head/CHANGES?view=log は svnweb からも参照できます。

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 ベースの検索エンジン https://bugs.freebsd.org/bugzilla/query.cgi で調べるのは 1, 2 分程度しかかかりません (もちろん、 誰もがときどきこれを忘れてしまうという罪を犯しています)。

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

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

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

4.2. 始める前に

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

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

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

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

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

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

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

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

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

電子メールの雛型には、次の 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] (角括弧を含みます) を追加して、 障害報告の Classmaintainer-update にするようにしてください。

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

  • Priority (優先順位): このフィールドには、 このバグがどの範囲に影響をおよぼしうるかを示します。

  • 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 のバージョン。 この項目は入力する必要があります。

最後に、一連の複数行フィールドがあります。

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

  • Description: あなたが経験した問題の完全で正確な説明。 開発者が誤解してしまうかもしれないので、 問題の原因について正しく追跡ができたと確信していない限り、 推測は避けるようにしてください。

  • How-To-Repeat: 問題を再現させるために取る必要のある行動の概要。

  • Fix: できればパッチか、少なくとも回避方法を記述する (同じ問題を回避する方法として他の人達の助けになるだけではなく、 開発者が問題の原因を理解する役に立つかもしれません) べきですが、 はっきりとしたアイデアがなければ開発者が思索をめぐらすために、 このフィールドは空にしておけば良いでしょう。

4.5. 障害報告を送信する

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

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

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

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

5. フォローアップ

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

誰かがあなたに追加情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 フォローアップを提出してください。 バグが修正されない一番の理由は、 提出者とのコミュニケーション不足が原因です。

  • 一番楽なのは、 障害報告検索ページ から行ける、それぞれの障害報告の web ページのコメントオプションを利用することです。

問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 この障害報告は議論を終了することができます、 とコメントを送ってください。

時々、提出した障害報告が誰にも割り当てられなかったり、 コメントのない状態が 1, 2 週間続くことがあります。 障害報告のバックログが増えているときや、 休暇シーズンに起こり得ます。 提出した障害報告に注意が引かれない状況が何週間も続くようであれば、 その分野に興味を持っているコミッタを見つけると良いでしょう。

これには、幾つかの方法がありますが、以下の順番が好ましいでしょう。 それぞれのコミュニケーションチャネルへのコンタクトには数日開けてください。

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

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

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

メンテナやユーザ同様、これらの人々もボランティアであるため、 すぐには障害報告に対応出来ないかもしれません。 フォローアップには、 我慢強くそして一貫性を持って対応することが推奨されます。 また、そのように対応すると協力を得やすいでしょう。 十分な配慮や努力をもってフォローアップに臨めば、 提出した障害報告に対応してくれるコミッタが見つかるのも時間の問題です。

6. 問題が起きたら

バグシステムに関する問題を見つけたら、 バグとして提出してください。 まさにこの目的のためのカテゴリが用意されています。 もし障害報告の提出が難しいようであれば、バグマイスター () に連絡をしてください。

7. さらなる読みもの

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

索引

シンボル

障害報告, FreeBSD 障害報告の書き方