ddb8727a68
r21372 -> r26086 head/ja_JP.eucJP/articles/problem-reports/article.xml Submitted by: Hiroo Ono <hiroo _at_ jp dot FreeBSD dot org> References: [doc-jp-work 1755, 1769]
984 lines
36 KiB
XML
984 lines
36 KiB
XML
<?xml version="1.0" encoding="euc-jp" standalone="no"?>
|
||
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
|
||
"../../../share/xml/freebsd42.dtd" [
|
||
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//JA" "../../share/xml/entities.ent">
|
||
%entities;
|
||
]>
|
||
|
||
<!--
|
||
The FreeBSD Japanese Documentation Project
|
||
Original revision: r26086
|
||
$FreeBSD$
|
||
-->
|
||
|
||
<article lang='ja'>
|
||
<articleinfo>
|
||
<title>&os; 障害報告の書き方</title>
|
||
|
||
<legalnotice id="trademarks" role="trademarks">
|
||
&tm-attrib.freebsd;
|
||
&tm-attrib.cvsup;
|
||
&tm-attrib.ibm;
|
||
&tm-attrib.intel;
|
||
&tm-attrib.sparc;
|
||
&tm-attrib.sun;
|
||
&tm-attrib.general;
|
||
</legalnotice>
|
||
|
||
<abstract>
|
||
<para>この記事では、明瞭な障害報告 (Problem Report: PR) を
|
||
&os; プロジェクトに提出する方法を解説します。</para>
|
||
</abstract>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Dag-Erling</firstname>
|
||
<surname>Smørgrav</surname>
|
||
<contrib>寄稿: </contrib>
|
||
</author>
|
||
</authorgroup>
|
||
|
||
<pubdate>$FreeBSD$</pubdate>
|
||
|
||
<releaseinfo>$FreeBSD$</releaseinfo>
|
||
</articleinfo>
|
||
|
||
<indexterm><primary>障害報告</primary></indexterm>
|
||
|
||
<section id="pr-intro">
|
||
<title>はじめに</title>
|
||
|
||
<para>ソフトウェアの利用者として経験するもっともいらただしいことの一つは、
|
||
<quote>それはバグじゃない</quote>、<quote>ひどい障害報告だ</quote>
|
||
などのようなそっけなく理解の役に立たない説明によって、
|
||
障害報告があっさり片付けられてしまうことです。
|
||
同様に、ソフトウェア開発者が経験するもっともいらだたしいことの一つは、
|
||
実際は障害報告ではない単なるサポート要求や
|
||
何が問題でどのように再現するかについての情報が
|
||
乏しいまたは欠落している障害報告が殺到することです。</para>
|
||
|
||
<para>この記事のねらいは、上手な障害報告の書き方について説明することです。
|
||
上手な障害報告とはどういうものでしょうか?
|
||
そうですね、単刀直入に要点を言えば、
|
||
上手な障害報告とは、迅速に解析を進め処理を行うことができ、
|
||
利用者と開発者がお互いに満足できるものです。</para>
|
||
|
||
<para>この記事では主として &os; の障害報告に焦点を絞っていますが、
|
||
他のソフトウェアプロジェクトでも多くの部分が当てはまるでしょう。</para>
|
||
|
||
<para>この記事はテーマ別に整理されており、順番に読めるようにはなっていません。
|
||
そのため、段階を踏んだチュートリアルとして利用するのではなく、
|
||
障害報告を提出する前に全体を通して読むべきです。</para>
|
||
</section>
|
||
|
||
<section id="pr-when">
|
||
<title>いつ障害報告を提出すればよいのか</title>
|
||
|
||
<para>問題にはさまざまな種類がありますが、
|
||
それらすべてが障害報告に値するわけではありません。
|
||
もちろん、誰しもが完璧ではありませんので、
|
||
実際はコマンドの構文を勘違いしていたり、
|
||
設定ファイルを書き間違えているのに、
|
||
プログラムにバグを見つけた! と思い込んでしまうことがあるでしょう
|
||
(とは言っても、それ自身、文書が適切に記述されていなかったり、
|
||
アプリケーションのエラー処理が甘いことを暗示している可能性があります)。
|
||
それ以外にも、障害報告を提出することが正しい行動では<emphasis>なく</emphasis>、
|
||
あなたや開発者たちに不満を抱かせるだけという場合があります
|
||
(訳注: はっきりと把握していないことを報告すべきではありません。
|
||
要領を得ない障害報告は扱いにくいものです)。
|
||
逆に、バグではありませんが障害報告を提出するのにふさわしい場合もあります
|
||
—
|
||
たとえば、既存機能の拡張や新しい機能の搭載要求のようなものです。</para>
|
||
|
||
<para>では、何がバグで何がバグでないのか、
|
||
どのようにして決めれば良いでしょうか?
|
||
簡単な経験則では、それを質問として (よくあるのは
|
||
<quote>どうすれば X できますか?</quote> や
|
||
<quote>Y はどこで見つけることができますか?</quote> のような形式で)
|
||
表現できるなら、あなたの問題はバグでは<emphasis>ありません</emphasis>。
|
||
いつも白黒がつけられるわけではありませんが、
|
||
この質問規則は大半の場合にあてはまります。
|
||
もし、このような質問に対する答えを求めているのなら、
|
||
&a.questions; で質問してみてください。</para>
|
||
|
||
<note>
|
||
<title>訳注</title>
|
||
|
||
<para>&a.questions; へのメールは英語でお願いします。
|
||
日本語での質問は、&a.jp.users-jp; や
|
||
<ulink url="http://www.flathill.gr.jp/~flathill/FreeBSD/FreeBSD-beginners-jp.html">FreeBSD-beginners-jp メーリングリスト</ulink>
|
||
などに送ってください。</para>
|
||
</note>
|
||
|
||
<para>バグではないものに関する障害報告を提出することが適切と考えられるのは、
|
||
以下のような場合です。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>機能拡張の要求。
|
||
一般的には、障害報告を提出する前に、
|
||
メーリングリストに要求を流すとよいでしょう。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>外部で管理されているソフトウェアの更新通知
|
||
(主に ports のことですが、BIND やさまざまな
|
||
GNU ユーティリティのような外部で維持されている、
|
||
システムの基礎を構成するソフトェアも含まれます)。</para>
|
||
|
||
<para>メンテナンスされていない ports (<makevar>MAINTAINER</makevar>
|
||
が <literal>ports@FreeBSD.org</literal> になっています)
|
||
では、この手の更新通知は興味を抱いた committer
|
||
が取り上げるかもしれませんし、あなたがその port
|
||
を更新するパッチを提出することが求められるかもしれません。
|
||
あらかじめパッチを提出すれば、port
|
||
がただちに更新される可能性が非常に高くなります。</para>
|
||
|
||
<para>port がメンテナンスされている場合は、
|
||
一次配布元から新たなバージョンがリリースされたことを通知する障害報告は
|
||
committer に余分な作業をさせるだけであまり役に立たないかもしれません。
|
||
また、メンテナは新しいバージョンが出たことをすでに知っている可能性が高いです。
|
||
もしかすると、開発者と一緒に作業していて、
|
||
退行したところがないかなどをテストしているところかもしれません。</para>
|
||
|
||
<para>いずれの場合も、<ulink
|
||
url="&url.books.porters-handbook;/port-upgrading.html">Port
|
||
作成者のためのハンドブック</ulink>
|
||
で説明されている手順がもっともよい結果をもたらします。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>再現することができないバグは、めったに直すことができません。
|
||
もし、バグが一度だけ発生してそれが再現できないもので、
|
||
なおかつ他の人のシステムでも起こらないようであれば、
|
||
開発者がそれを再現できる可能性も、
|
||
何が悪いのかわかる可能性もありません。
|
||
これはバグが起こらなかったことを意味するわけではありません。
|
||
しかし、このような状況ではあなたの障害報告がバグの修正に
|
||
つながる見込みは非常に薄いものです。
|
||
おまけに、この手のバグは実際は故障したハードディスクや過熱した
|
||
CPU が原因で起きていることが多いのです
|
||
(障害報告を提出する前には必ず、可能なら、
|
||
こうした原因を排除するよう努めるべきです)。</para>
|
||
|
||
<para>それから、問題が時宜を得たものか確認すべきです。
|
||
既に修正したバグに関する障害報告を受けとることほど開発者を悩ませるものはまずありません。</para>
|
||
</section>
|
||
|
||
<section id="pr-prep">
|
||
<title>準備</title>
|
||
|
||
<para>従うべき良い規則は、
|
||
障害報告を提出する前に常に問題の背景を調べることです。
|
||
あなたの問題はすでに報告されているかもしれません。
|
||
また、メーリングリストで議論されている最中か、
|
||
最近議論されていたかもしれません。
|
||
あなたが動かしているものより新しいバージョンで、
|
||
既に修正済みということすらありえます。
|
||
ですから、障害報告を提出する前に自明な場をすべて確認すべきです。
|
||
&os; については、以下のところになります。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>&os; の
|
||
<ulink url="&url.books.faq;/index.html">よくある質問とその答え</ulink>
|
||
(FAQ) 一覧。
|
||
FAQ は、
|
||
<ulink url="&url.books.faq;/books/faq/hardware.html">ハードウェア互換性</ulink>、
|
||
<ulink url="&url.books.faq;/books/faq/applications.html">ユーザアプリケーション</ulink> や
|
||
<ulink url="&url.books.faq;/books/faq/kernelconfig.html">カーネルコンフィグレーション</ulink>
|
||
といったことに関する広い範囲の質問に対して答を示そうとしています。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>
|
||
<ulink
|
||
url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">
|
||
メーリングリスト</ulink>。
|
||
— メーリングリストを購読していなければ、
|
||
&os; のウェブサイトにある
|
||
<ulink
|
||
url="http://www.FreeBSD.org/ja/search/search.html#mailinglists">
|
||
アーカイブ検索</ulink>を使ってください。
|
||
もし、メーリングリストで議論がされていなければ、
|
||
自分の問題についてのメッセージを送ってみて、
|
||
見落とした点を誰かが見つけてくれるかどうか
|
||
数日間待ってみると良いでしょう。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>ウェブ全体を検索する (任意)。—
|
||
あなたの問題に関係する話題がないか
|
||
あなたのお気に入りの検索エンジンを使って探してください。
|
||
あなたが知りもしなかったか、
|
||
検索しようと考えなかったメーリングリストやニュースグループのアーカイブにあたることもあるかもしれません。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>次に、検索可能な
|
||
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
||
&os; 障害報告データベース</ulink> (GNATS) があります。
|
||
あなたの問題が新しいものでも不明瞭でもなければ、
|
||
既に報告されている可能性がかなり高いです。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>何よりもまず、
|
||
元となるソースコード内のドキュメントで、
|
||
あなたの問題が触れられていないか調べてみるべきです。</para>
|
||
|
||
<para>&os; の基本部分のコードについては、
|
||
システムの <filename>/usr/src/UPDATING</filename> ファイルの内容か、
|
||
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>
|
||
にある最新版をよく調べるべきです
|
||
(あるバージョンから別のバージョンにアップグレードしようとしているのであれば
|
||
—特に
|
||
<literal>-current</literal> ブランチに上げようとしているなら、
|
||
これは非常に重要な情報です)。</para>
|
||
|
||
<para>しかし、問題が &os; Ports Collection
|
||
からインストールされたものにあるのであれば、
|
||
<filename>/usr/ports/UPDATING</filename> (個別の ports)
|
||
または <filename>/usr/ports/CHANGES</filename>
|
||
(Ports Collection 全体に影響する変更) を参照すべきです。
|
||
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING"></ulink> と
|
||
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES"></ulink>
|
||
は CVSweb からも参照できます。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>次に、障害報告が適切な人物に届くことを確認する必要があります。</para>
|
||
|
||
<para>まず、問題がサードパーティソフトウェア
|
||
(あなたがインストールした port または package)
|
||
のバグであれば、原作者に報告すべきで、&os;
|
||
プロジェクトに報告すべきではありません。
|
||
このルールには二つの例外があります。
|
||
一つ目は、バグが他のプラットフォームで発生しない場合です。
|
||
この場合は、&os; への移植に原因がある可能性があります。
|
||
二つ目は、原作者がバグを既に修正していて、
|
||
そのソフトウェアの新しいバージョンかパッチを公開しているのに、
|
||
&os; の port がまだ更新されていない場合です。</para>
|
||
|
||
<para>それから、&os; のバグ追跡システムは
|
||
発信者が選択した分類に従って
|
||
障害報告を分別しているということに注意してください。
|
||
もし間違った分類を選択した場合、あなたが送った障害報告は
|
||
誰かが再分類する良い機会がくるまでしばらく見落とされるでしょう。</para>
|
||
</section>
|
||
|
||
<section id="pr-writing">
|
||
<title>障害報告の書き方</title>
|
||
|
||
<para>問題が障害報告を行うに値すると結論を出し、
|
||
そしてそれが &os; の問題点であると判断したら、
|
||
実際に障害報告を執筆する時です。
|
||
障害報告を作成して送信するプログラムの仕組みに入る前に、
|
||
障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。</para>
|
||
|
||
<section>
|
||
<title>よい障害報告を書くこつ</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><emphasis><quote>Synopsis</quote>(概要)
|
||
行を空のままにしないでください。</emphasis>
|
||
障害報告は、世界中に配布されるメーリングリストに送られる
|
||
(そこでは、<quote>Synopsis</quote> (概要) は
|
||
<literal>Subject:</literal> 行に使われます) と共に、
|
||
データベースにも入れられます。後でデータベースを synopsis (概要)
|
||
で参照する人は、題がついていない障害報告は単に無視することでしょう。
|
||
このデータベースに登録された障害報告は、
|
||
誰かが対応済にするまでは残っていることを忘れないでください。
|
||
内容不明のものは大抵雑音に埋もれてしまいます。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>わかりにくい<quote>Synopsis</quote> (概要)
|
||
行は避けましょう。</emphasis>
|
||
あなたが提出した障害報告を読む人がどういう状況か分かっていると仮定すべきではありません。
|
||
できるだけ詳しく書きましょう。
|
||
たとえば、その問題はシステムのどの部分にあてはまるのでしょうか。
|
||
インストール中にしか問題に当たらないのか、それとも稼働中に当たるのか。
|
||
具体的な例でいうなら、
|
||
<literal>Synopsis: portupgrade is broken</literal>
|
||
(概要: portupgrade がおかしい) ではなく、
|
||
次のように書いたらどれだけ伝わりやすいか考えてみてください。
|
||
<literal>Synopsis: port sysutils/portupgrade coredumps on
|
||
-current</literal> (概要: sysutils/portupgrade port が
|
||
-current でコアダンプします)。(ports の場合は、
|
||
<quote>Synopsis</quote> (概要) 行に分類と名前を入れると、
|
||
とても助かります)。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>パッチがあるなら、そう書いてください。</emphasis>
|
||
パッチがついている障害報告は、
|
||
ついていないものよりも見てもらえる可能性が高いです。パッチをつける場合は、
|
||
<quote>Synopsis</quote> (概要) 行の先頭に
|
||
<literal>[patch]</literal> という文字列をいれて下さい。
|
||
(この通り書かなければならないというわけではありませんが、
|
||
慣習としてこの文字列が用いられています)。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>あなたがメンテナなら、そう書いてください。</emphasis>
|
||
ソースコードの一部 (たとえば、ある port)
|
||
をメンテナンスしているなら、概要行の先頭に
|
||
<literal>[maintainer update]</literal>
|
||
という文字列をできればいれて、障害報告の
|
||
<quote>Class</quote> を必ず
|
||
<literal>maintainer-update</literal>
|
||
にしてください。こうすれば、committer
|
||
がその障害報告を扱う際に、いちいち確認する必要がありません。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>具体的に書いてください。</emphasis>
|
||
あなたが抱えている問題について多くの情報を出すほど、
|
||
回答してもらえる可能性は高くなります。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>&os; のバージョン
|
||
(これを記載する場所があります。後述します)
|
||
と、どのアーキテクチャで動かしているのかを書いてください。
|
||
動かしているのが (CDROM から、またはダウンロードして入れた)
|
||
リリースでなのか、それとも
|
||
&man.cvsup.1; でメンテナンスしているシステムでなのか
|
||
(そうだとしたら、最後に更新したのはいつか)
|
||
も書いてください。あなたが &os.current;
|
||
ブランチを追いかけていたら、それを真っ先に聞かれるでしょう。
|
||
なぜなら、&os.current; では (注目を浴びる問題は特に)
|
||
修正がすぐに入る傾向があり、&os.current;
|
||
のユーザはそれについて行くことが求められているからです。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>make.conf</filename>
|
||
に、どのグローバルオプションを指定したか書いてください。
|
||
注意: &man.gcc.1; に <literal>-O2</literal>
|
||
以上を設定するのは、多くの場合にバグがあることが分かっています。
|
||
&os; 開発者はパッチを受け取るでしょうが、
|
||
単純に時間とボランティアが少ないため、
|
||
そのような問題は通常調査したがらず、
|
||
ただ対応していないだけだと答える可能性があります。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>カーネルの問題なら、
|
||
次の情報を渡せるようにしておいてください
|
||
(はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、
|
||
関係があると思う部分の抜粋は入れるべきです)。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>カーネルコンフィグレーション
|
||
(どのハードウェアデバイスがインストールされているかも含む)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>(<literal>WITNESS</literal> などの)
|
||
デバッグオプションを有効にしているか、
|
||
しているなら、
|
||
そのオプションを変更しても問題は変わらないか</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>もし生成しているなら、バックトレース</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><filename>src/UPDATING</filename>
|
||
は読んだか、そこにあなたの問題が挙がっていないか
|
||
(間違いなく聞かれます)</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para>代替として動かせるカーネルが他にないか
|
||
(これは、故障したディスクや過熱した CPU
|
||
などのハードウェアに関連した問題で、
|
||
カーネルの問題に見えるものを除外するためです)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Ports の問題であれば、
|
||
次の情報を渡せるようにしておいてください
|
||
(はじめから入れるのは単にデータベースを一杯にするだけなので必要ありませんが、
|
||
関係があると思う部分の抜粋は入れるべきです)。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>どの ports をインストールしたのか</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><makevar>PORTSDIR</makevar>
|
||
など、<filename>bsd.port.mk</filename>
|
||
のデフォルトを上書きする環境変数すべて</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><filename>ports/UPDATING</filename>
|
||
は読んだか、そこにあなたの問題が挙がっていないか
|
||
(間違いなく聞かれます)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>漠然と機能を要求するのはやめましょう。</emphasis>
|
||
<quote>誰かこういうことするものを実装すべきだ</quote>
|
||
という形の障害報告は、詳細な要望に比べて成果を得にくいものです。
|
||
ソースコードは誰でも利用できるのですから、何か機能が欲しければ、
|
||
それをいれる最善の手段は作業にとりかかることです。
|
||
また上述したように、こういうことは多くの場合、
|
||
障害報告データベースに登録するよりも
|
||
<literal>freebsd-questions</literal> で議論した方がよいでしょう。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>誰かが既に似たような障害報告を提出していないか確認してください。</emphasis>
|
||
これは、既に述べたことではありますが、ここで繰り返しておくに値するでしょう。
|
||
Web ベースの検索エンジン
|
||
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>
|
||
で調べるのは 1, 2 分程度しかかかりません。
|
||
(もちろん、誰もがときどきこれを忘れてしまうという罪を犯しています)。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>異論のある要望は出さないようにしましょう。</emphasis>
|
||
あなたの障害報告がかつて論争になった分野に関するものであったら、
|
||
パッチを提出するだけでなく、そのパッチが
|
||
<quote>正当なものである</quote> 根拠も提出したほうがよいかもしれません。
|
||
どの場合でも上述のように
|
||
<ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink>
|
||
でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>礼儀正しくしましょう。</emphasis>
|
||
あなたの障害報告について作業する人は、
|
||
ほとんど全員がボランティアです。
|
||
金銭的収入以外の動機から行なっていることを、
|
||
やれと命令されるのは誰も好きではありません。
|
||
オープンソースプロジェクトに関しては、
|
||
これを常に念頭においておくとよいでしょう。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section>
|
||
<title>始める前に</title>
|
||
|
||
<para>&man.send-pr.1; プログラムを使うなら、環境変数
|
||
<envar>VISUAL</envar> (もし <envar>VISUAL</envar>
|
||
が設定されていなければ <envar>EDITOR</envar>)
|
||
が意味のあるものに設定されているか確認しましょう。</para>
|
||
|
||
<para>また、メール配送ソフトウェアが正常に動作することも確認してください。
|
||
&man.send-pr.1; は障害報告の提出と追跡にメールを利用します。
|
||
&man.send-pr.1; を動かすマシンからメールを送ることができないと、
|
||
あなたの障害報告は GNATS データベースに届きません。
|
||
&os; におけるメールの設定の詳細については
|
||
&os; ハンドブックの <quote>電子メール</quote> の章
|
||
<ulink url="&url.books.handbook;/mail.html"></ulink>
|
||
をご覧ください。</para>
|
||
|
||
<para>あなたが使っているメーラが GNATS
|
||
に送るメッセージに手を加えないことを確かめておいてください。
|
||
特に、メーラが自動で改行したり、タブをスペースに変更したり、
|
||
改行文字をエスケープしたりすると、
|
||
提出したパッチは使えないものになってしまいます。
|
||
もっとも、テキスト部については障害報告を web
|
||
で表示した時に読みやすいように、
|
||
70 文字前後で改行を入れることをお願いしています。</para>
|
||
|
||
<para>&man.send-pr.1; の代わりに
|
||
web ベースの障害報告提出を利用する場合も、同様の配慮が必要です。
|
||
カットアンドペースト操作はテキストをフォーマットするのに副作用がある場合があるので気をつけてください。
|
||
場合によっては、パッチが変更されずに届くように、&man.uuencode.1;
|
||
を使わなければならないかもしれません。</para>
|
||
|
||
<para>最後に、提出物が長くなってしまうなら、
|
||
提出時に問題が起きて失われてしまうことのないように、
|
||
オフラインで準備しておきましょう。
|
||
これは特に web フォームで問題になります。</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>パッチやファイルを添付する</title>
|
||
|
||
<para>&man.send-pr.1; プログラムは、
|
||
障害報告にファイルを添付する機能を備えています。
|
||
それぞれのファイルの基本名称
|
||
(すなわち、パスを除いたファイルそのものの名前)
|
||
が一意でありさえすれば、好きなだけ添付できます。
|
||
コマンドラインオプション <option>-a</option>
|
||
で添付するファイルの名前を指定してください。</para>
|
||
|
||
<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput></screen>
|
||
|
||
<para>添付するファイルがバイナリであっても心配しないでください。
|
||
メールエージェントが混乱しないように、自動的に符合化されます。</para>
|
||
|
||
<para>パッチは context 形式か unified 形式の差分を &man.diff.1; の
|
||
<option>-c</option> か <option>-u</option>
|
||
オプションを使って作成してください (unified 形式の方が好まれます)。
|
||
パッチを添付する場合、
|
||
開発者があなたの報告を読んで簡単にパッチを適用できるように、
|
||
修正したファイルの正確な CVS のリビジョン番号が特定できるか確認してください。
|
||
カーネルやベースのユーティリティに関しては、新しいコードはすべて
|
||
&os.current; (CVS の HEAD ブランチ)
|
||
でテストするべきなので、それに対するパッチが望ましいです。
|
||
適切か十分なテストが行なわれたら、そのコードは
|
||
&os.stable; ブランチにマージまたは移植されます。</para>
|
||
|
||
<para>パッチを添付するのではなく本文中に含める場合、
|
||
もっともありがちな問題は、
|
||
電子メールプログラムによってはタブをスペースに変更してしまい、
|
||
Makefile に含めるつもりだったものを台無しにしてしまうことです。</para>
|
||
|
||
<para>パッチを
|
||
<command>Content-Transfer-Encoding: quoted-printable</command>
|
||
を利用した添付ファイルとして送らないようにしてください。
|
||
これは文字をエスケープしてしまい、
|
||
パッチ全体が使い物にならなくなります。</para>
|
||
|
||
<para>また、障害報告の中に小さなパッチを含めるのは
|
||
(とりわけ説明されている障害を修正する場合は) 大抵問題ないのですが、
|
||
大規模なパッチや新しいコードの場合は十分な査読を行なった後にコミットすべきであるため、
|
||
パッチを Web や FTP サーバに置き、その URL を障害報告に書くようにしてください。
|
||
電子メールに含めたパッチはサイズが大きいと分割される傾向にあり
|
||
(とりわけ GNATS が処理に関わるときはそうなります)、
|
||
パッチが大きいほど興味をもった人がつなぎ直すのが面倒になります。
|
||
また、Web にパッチをおけば、
|
||
元の障害報告へのフォローアップとしてパッチ全体を再提出しなくても変更できます。
|
||
最後に、大きなパッチはデータベースのサイズをとにかく増やしてしまいます。
|
||
閉じられた障害報告は実際に消されることはなく、
|
||
保持されたまま <literal>closed</literal>
|
||
という印をつけられるだけだからです。</para>
|
||
|
||
<para>また、障害報告かパッチ自体に明確に指定がなければ、
|
||
あなたが提出したパッチは修正した元のファイルと同じ条件の
|
||
ライセンス下にあるものと仮定されることに留意しておくべきです。</para>
|
||
</section>
|
||
|
||
<section>
|
||
<title>テンプレートに記入する</title>
|
||
|
||
<para>&man.send-pr.1; を動かすとテンプレートが表示されます。
|
||
テンプレートは特定の項目から成り立っており、
|
||
その一部にはあらかじめ埋められていたり、
|
||
その項目の目的の解説やそこに記入できる値の一覧が記載されていたりします。
|
||
コメントの部分は、自分で変更・削除しなくても、
|
||
自動的に削除されますので心配する必要はありません。</para>
|
||
|
||
<para>テンプレートの先頭にある <literal>SEND-PR:</literal>
|
||
と書かれている行の下が電子メールのヘッダです。
|
||
通常、この部分を変更する必要はありませんが、
|
||
障害報告を送信する機械やアカウントで
|
||
メールを出すことはできても受けとることはできない場合、
|
||
<literal>From:</literal> と <literal>Reply-To:</literal>
|
||
に実際のメールアドレスを設定すべきです。
|
||
また、自分 (や他の誰か) に障害報告の複製を送りたい場合は、
|
||
電子メールアドレスを
|
||
<literal>Cc:</literal> ヘッダに追加してください。</para>
|
||
|
||
<para>次に、一連の一行フィールドが続きます。</para>
|
||
|
||
<note>
|
||
<title>訳注</title>
|
||
|
||
<para>フィールドの意味が分かり易いように
|
||
フィールド名を訳していますが、
|
||
フィールドの値も含めて
|
||
実際のフィールド名は英文字でなければなりません。</para>
|
||
</note>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><emphasis>Submitter-Id (提出者-Id):</emphasis>
|
||
これは変更しないでください。
|
||
あなたが &os.stable; を動かしている場合でも、既定値である
|
||
<literal>current-users</literal> が正しいのです。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Originator (あなたの名前):</emphasis>
|
||
これは普通、現在ログインしているユーザの
|
||
<literal>gecos</literal> フィールドを使って既に埋められています。
|
||
あなたの実際の名前を指定してください。
|
||
お好みで、名前の後ろに電子メールアドレスを
|
||
山括弧 (< と > のこと) で閉じて付けることができます。</para>
|
||
|
||
<note>
|
||
<title>訳注</title>
|
||
|
||
<para>たとえば、以下のように書くことができます。</para>
|
||
|
||
<screen>From: <userinput>FreeBSD Taro <FreeBSD-Taro@example.org></userinput></screen>
|
||
</note>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Organization (所属組織):</emphasis>
|
||
あなたの好きなようにしてください。
|
||
このフィールドは何らかの深い意味で使われることはありません。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Confidential (機密):</emphasis>
|
||
これは <literal>no</literal> で既に埋められています。
|
||
機密扱いの &os; 障害報告というものはないため、
|
||
変更することに意味はありません。—
|
||
障害報告データベースは <application>CVSup</application>
|
||
によって、世界的に配布されています。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Synopsis (概要):</emphasis>
|
||
問題についての簡にして要を得た説明を書き込んでください。
|
||
概要は障害報告メールのサブジェクトとして利用されており、
|
||
一覧や要旨にも使われています。
|
||
概要が不明瞭な障害報告は無視される傾向があります。</para>
|
||
|
||
<para>上述したように、障害報告にパッチが含まれているなら、
|
||
概要の先頭に <literal>[patch]</literal> と書いて下さい。
|
||
あなたがメンテナなら、
|
||
<literal>[maintainer update]</literal> を追加して、
|
||
障害報告の <quote>Class</quote> を
|
||
<literal>maintainer-update</literal>
|
||
にするようにしてください。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Severity (重要度):</emphasis>
|
||
<literal>non-critical (重要ではない)</literal>、
|
||
<literal>serious (重要)</literal>、
|
||
<literal>critical (致命的) </literal> のどれかです。
|
||
重要度を過大に評価しないでください。
|
||
あなたの問題が本当に致命的 (たとえば、
|
||
<username>root</username> 権限を悪用できたり、
|
||
パニックを容易に再現できるなど) でない場合は、
|
||
<literal>critical</literal>
|
||
に分類するのを、また多くの人に影響するのでなければ
|
||
(特定のデバイスドライバやシステムユーティリティ)、
|
||
<literal>serious</literal>
|
||
に分類するのを控えてください。
|
||
まったく同じことをやった人があまりに多いため、
|
||
問題の重要性を水増ししても、必ずしも
|
||
&os; 開発者がその問題に早くとりかかるわけではありません。
|
||
— 実際、
|
||
それが理由でこのフィールドや次のフィールドにほとんど注意を払わない開発者もいます。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Priority (優先順位):</emphasis>
|
||
<literal>low (低い)</literal>、
|
||
<literal>medium (中間)</literal>、
|
||
<literal>high (高い)</literal> のどれかです。
|
||
<literal>high (高い)</literal>
|
||
は実質的にすべての &os; ユーザに影響するもの、
|
||
<literal>medium (中間)</literal>
|
||
は多くのユーザに影響するものに限定すべきです。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Category (分類):</emphasis>
|
||
以下から一つを選んでください (
|
||
<ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/gnu/usr.bin/send-pr/categories"></ulink>
|
||
からもってきています)。</para>
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>advocacy:</literal>
|
||
&os; の世間的なイメージに関する問題。
|
||
めったに使われません。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>alpha:</literal>
|
||
Alpha プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>amd64:</literal>
|
||
AMD64 プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>bin:</literal>
|
||
基本システムに含まれるユーザランドプログラムに関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>conf:</literal>
|
||
設定ファイルや、既定値などに関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>docs:</literal>
|
||
マニュアルページ、オンライン文書に関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>gnu:</literal>
|
||
&man.gcc.1; や &man.grep.1; などの
|
||
GNU ソフトウェアに関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>i386:</literal>
|
||
&i386; プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>ia64:</literal>
|
||
ia64 プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>java:</literal>
|
||
&java; 仮想マシンに関する問題。
|
||
(&java; に依存しているだけの ports は
|
||
<literal>ports</literal> に分類すべきです)。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>kern:</literal>
|
||
カーネルまたは (特定のプラットフォーム用ではない)
|
||
デバイスドライバに関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>misc:</literal>
|
||
これらの分類に適合しないその他の分類
|
||
(なお、ここに分類されると見失われやすいです)。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>ports:</literal>
|
||
ports ツリーに関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>powerpc:</literal>
|
||
&powerpc; プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>sparc64:</literal>
|
||
&sparc64; プラットフォーム固有の問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>standards:</literal>
|
||
標準規格への適合問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>threads:</literal>
|
||
&os; のスレッド実装 (特に &os.current; 上のもの)
|
||
に関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>usb:</literal>
|
||
&os; の USB 実装に関する問題。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>www:</literal>
|
||
&os; ウェブサイトへの変更と改善。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Class:</emphasis> 以下から一つを選んでください。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><literal>sw-bug:</literal>
|
||
ソフトウェアのバグ。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>doc-bug:</literal>
|
||
文書中の間違い。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>change-request:</literal>
|
||
機能の追加や、既存の機能の変更についての要望。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>update:</literal>
|
||
ports やその他の寄贈ソフトウェアに対する更新。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><literal>maintainer-update:</literal>
|
||
あなたが保守している ports の更新。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Release:</emphasis>
|
||
あなたが動作させている &os; のバージョン。
|
||
これは &man.send-pr.1; によって自動的に書き込まれますが、
|
||
あなたが障害が起きているものと違うシステムから障害報告を送信する場合に限り、
|
||
変更する必要があります。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>最後に、一連の複数行フィールドがあります。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><emphasis>Environment (環境):</emphasis>
|
||
問題が発生した環境を可能な限り正確に記述すべきです。
|
||
ここには、オペレーティングシステムのバージョン、
|
||
特定のプログラムのバージョンまたは問題があるファイル、
|
||
そしてシステムの設定などのような関係する項目、
|
||
問題に影響を及ぼすインストールしたその他の
|
||
ソフトウェアなどが含まれます。—
|
||
手短にいうなら、その問題が生じる環境を再構築するために、
|
||
開発者が知らなければならないことすべてです。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Description:</emphasis>
|
||
あなたが経験した問題の完全で正確な説明。
|
||
開発者が誤解してしまうかもしれないので、
|
||
問題の原因について正しく追跡ができたと確信していない限り
|
||
推測は避けるようにしてください。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>How-To-Repeat:</emphasis>
|
||
問題を再現させるために取る必要のある行動の概要。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis>Fix:</emphasis>
|
||
できればパッチか、少なくとも回避方法を記述する
|
||
(同じ問題を回避する方法として他の人達の助けになるだけではなく、
|
||
開発者が問題の原因を理解する役に立つかもしれません) べきですが、
|
||
はっきりとしたアイデアがなければ開発者が思索をめぐらすために、
|
||
このフィールドは空にしておけば良いでしょう。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section>
|
||
<title>障害報告を送信する</title>
|
||
|
||
<para>テンプレートを埋め、保存してエディタを終了すると、
|
||
&man.send-pr.1; は
|
||
<prompt>s)end, e)dit or a)bort?</prompt>
|
||
と表示して指示を求めます。
|
||
<userinput>s</userinput> を押せば障害報告の提出に進めますし、
|
||
<userinput>e</userinput> だとエディタが再び実行され、
|
||
ひきつづき編集できます。
|
||
<userinput>a</userinput> なら作業を中止します。
|
||
abort を選択した場合、いままで書いていた障害報告はディスクに残りますので
|
||
(&man.send-pr.1; は終了前にそのファイル名を示します)、
|
||
暇な時にそれを編集したり、場合によっては
|
||
よりネットワーク接続性のよいシステムに持っていくことができるでしょう。
|
||
この作業ファイルは、&man.send-pr.1; の
|
||
<option>-f</option> オプションを使って送ることができます。</para>
|
||
|
||
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
|
||
|
||
<para>上記の操作では、指定されたファイルを読み込み、
|
||
書式が正しいか検証し、ファイル中のコメント部分を取り除いて、
|
||
障害報告が送信されます。</para>
|
||
</section>
|
||
|
||
</section>
|
||
|
||
<section id="pr-followup">
|
||
<title>フォローアップ</title>
|
||
|
||
<para>障害報告を提出すると、
|
||
障害報告に割り当てられた追跡用の番号と状況を確認するために利用する
|
||
URL を含む、確認のための電子メールが送られてくるでしょう。
|
||
ちょっぴり運がよければ、
|
||
誰かがあなたの問題に興味を持ってそれに取り組もうとするでしょうし、
|
||
場合によってはなぜそれが問題でないか説明してくれるでしょう。
|
||
状況に何かの変更があると、
|
||
誰かがあなたの障害報告を審査追跡状態にして、
|
||
何らかのコメントかパッチの通知を自動的に受けとるでしょう。</para>
|
||
|
||
<para>誰かがあなたに追加情報を求めたり、
|
||
最初の報告の中で言及しなかったものを思い出したり発見したら、
|
||
次の 2 つの方法のどちらかで、フォローアップを提出してください。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>一番楽なのは、
|
||
<ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
||
障害報告検索ページ</ulink> から行ける、それぞれの障害報告の
|
||
web ページのフォローアップリンクを利用することです。
|
||
このリンクをクリックすると、
|
||
(ブラウザがそうするように設定されていれば)
|
||
正しい To: および Subject:
|
||
行を埋めた電子メール画面が表示されます。</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>または、
|
||
バグ追跡システムがどの障害報告に加えればよいか判断できるように、
|
||
件名に追跡番号が含まれているか確かめて
|
||
&a.bugfollowup; にメールを送るだけでも構いません。</para>
|
||
|
||
<note>
|
||
<para>追跡番号を <emphasis>含めない</emphasis> と、
|
||
GNATS は混乱して、新規に障害報告を生成して、それを
|
||
GNATS 管理者に割り当てます。
|
||
そうなると、誰かがゴミを片付けにくるまで、
|
||
何日または何週間も見失われたままになります。</para>
|
||
|
||
<para>間違ったやり方: <programlisting>Subject: that PR I sent</programlisting>
|
||
正しいやり方: <programlisting>Subject: Re: ports/12345: compilation problem with foo/bar</programlisting></para>
|
||
</note>
|
||
</listitem>
|
||
|
||
</itemizedlist>
|
||
|
||
<para>問題がなくなったのに障害報告の処理が完了していなければ、
|
||
できれば、どのように、いつ、問題を解決できたかの説明を添えて、
|
||
この障害報告は議論を終了することができます、と
|
||
(前述の方法で) フォローアップを送ってください。</para>
|
||
</section>
|
||
|
||
<section id="pr-further">
|
||
<title>さらなる読みもの</title>
|
||
|
||
<para>完全なものとはいえませんが、
|
||
適切な障害報告の書き方と手順について関連する資料を示します。</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><ulink
|
||
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
|
||
効果的にバグを報告するには</ulink>
|
||
(<ulink
|
||
url="http://www.unixuser.org/~ueno/bugs-ja.html">
|
||
日本語訳</ulink>) —
|
||
Simon G. Tatham 氏による、(&os; に限らない)
|
||
役に立つ障害報告の作成についてのすぐれたエッセイ。</para>
|
||
</listitem>
|
||
<listitem>
|
||
<para><ulink
|
||
url="&url.articles.pr-guidelines.en;/article.html">
|
||
障害報告 取り扱いガイドライン</ulink> —
|
||
障害報告が &os; の開発者によってどのように扱われるかについて
|
||
有益な見識をまとめた記事。</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
</article>
|