FreeBSD 障害報告の書き方
Prev |  | Next

# 4. 障害報告の書き方

自分の問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したのですから、 実際に障害報告を執筆する時です。 環境変数 `VISUAL` (か、もし `VISUAL` が設定されていなければ `EDITOR`) が何らかの使える値に設定されているか確認して、 send-pr(1) を実行します。

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

send-pr(1) プログラムは、 障害報告にファイルを添付する機能を備えています。 あなたが望む数だけ、それぞれ一意の名前を持ったファイル (すなわち、パスを除いた適切な名前のファイル) を添付することができます。 コマンドラインオプション `-a` で 添付するファイルの名前を指定してください。

    % send-pr -a /var/run/dmesg -a /tmp/errors

添付するファイルがバイナリであっても心配しないでください。 メールエージェントが混乱しないように、自動的に符合化が行われます。

パッチは context 形式か unified 形式の差分を diff(1) の `-c` か `-u` オプションを 使って作成してください。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 修正したファイルの正確な CVS のリビジョン番号が特定できるか 確認してください。

一般的に、 障害報告の中に小さなパッチを含める分にはいいのですが、 記載される問題についての修正が大規模な場合や新しいコードの場合は 十分な査読を行なった後にコミットすべきであるため、 パッチを Web や FTP サーバに置き、その URL を障害報告に含めてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり (とりわけ Gnats が処理に関わるときはそうです)、 肝心な部分が変にならないように注意をはらってください。 また、パッチに変更があった場合、 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくとも Web から該当部分のパッチを送信して変更することができます。

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

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

テンプレートは特定のフィールドから成り立っており、 あらかじめ書き込まれた部分がいくつかあります。そこには フィールドの目的が何かを説明する解説や そのフィールドに利用可能な値が書かれています。 コメントの部分は、自分で変更・削除しなくても、 自動的に削除されますので心配する必要はありません。

テンプレートの先頭にある `SEND-PR:` と書かれている行の下が電子メールのヘッダです。 通常、この部分を変更する必要はありませんが、 障害報告を送信する機械やアカウントで メールを出すことはできるが受けとることができない場合、 `From:` と `Reply-To:` に 実際のメールアドレスを設定すべきです。 また、自分 (や他の誰か) に障害報告の複製を送りたい場合は、 電子メールアドレスを `Cc:` ヘッダに追加してください。

次に、一連の一行フィールドが続きます。

> 訳注: フィールドの意味が分かり易いように フィールド名を訳していますが、 フィールドの値も含めて 実際のフィールド名は英文字である必要があります。

- Submitter-Id (提出者-Id): これは変更しないでください。 あなたが FreeBSD-STABLE を動かしている場合でも、既定値である `current-users` が正しいのです。

- Originator (あなたの名前): これは普通、現在ログインしているユーザの GECOS フィールドを使って既に埋められています。 あなたの実際の名前を指定してください。 お好みで、名前の後ろに電子メールアドレスを 山括弧 (< と > のこと) で閉じて付けることができます。

  > 訳注: たとえば、以下のように書くことができます。

  >     From: FreeBSD Taro <FreeBSD-Taro@example.org>

- Organization (所属組織): あなたが望むのなら好きに使えます。 このフィールドは何らかの深い意味で使われることはありません。

- Confidential (機密): これは `no` で既に埋められています。 機密扱いの FreeBSD 障害報告のようなものはないため、 変更することに意味はありません。-- 障害報告データベースは CVSup によって、 世界的に配布されています。

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

  障害報告にパッチを添付する場合、概要の先頭に `[PATCH]` と書いてください。

- Severity (重要度): `non-critical (重要ではない)`、 `serious (重要)`、 `critical (致命的)` のどれかです。 重要度を過大に評価しないでください。 あなたの問題が本当に致命的 (たとえば、 `root` 権限を悪用できたり、 パニックを容易に再現できるなど) でない場合は、 `critical` に分類するのは控えてください。 障害報告を提出する人達は自分の問題を大げさに評価しがちであり、 そのため開発者はこのフィールドや次のフィールドを無視する傾向があります。

- Priority (優先順位): `low (低い)`、 `medium (中間)`、 `high (高い)` のどれかです。 分類の基準は前述されてますので読んでください。

- Category (分類): 以下から一つを選んでください:

  - `advocacy:` FreeBSD の一般像に関する問題。めったに使われません。

  - `alpha:` Alpha プラットフォーム固有の問題。

  - `bin:` 基本システムに含まれるユーザランドプログラムに関する問題。

  - `conf:` 設定ファイルや、既定値などに関する問題。

  - `docs:` マニュアルページ、オンライン文書に関する問題。

  - `gnu:` gcc(1) や grep(1) などの GNU ソフトウェアに関する問題。

  - `i386:` i386 プラットフォーム固有の問題。

  - `ia64:` ia64 プラットフォーム固有の問題。

  - `java:` Java™ に関する問題。

  - `kern:` カーネルに関する問題。

  - `misc:` これらの分類に適合しないその他の分類。

  - `ports:` ports ツリーに関する問題。

  - `powerpc:` PowerPC プラットフォーム固有の問題。

  - `sparc64:` SPARC プラットフォーム固有の問題。

  - `standards:` 標準規格への適合問題。

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

## 4.3. 障害報告を送信する

テンプレートを書き終えて、 保存してエディタを終了すると、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

上記の操作では、指定されたファイルを読み込み、 書式が正しいか検証し、ファイル中のコメント部分を取り除いて、 障害報告が送信されます。

Prev | Home | Next
準備 |  | フォローアップ