Date: Fri, 28 Dec 2012 15:02:31 +0000 (UTC) From: Ryusuke SUZUKI <ryusuke@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r40488 - head/ja_JP.eucJP/articles/problem-reports Message-ID: <201212281502.qBSF2Vrb046871@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: ryusuke Date: Fri Dec 28 15:02:30 2012 New Revision: 40488 URL: http://svnweb.freebsd.org/changeset/doc/40488 Log: - Merge the following from the English version: r19282 -> r20986 head/ja_JP.eucJP/articles/problem-reports/article.xml Submitted by: Hiroo Ono <hiroo _at_ jp dot FreeBSD dot org> References: [doc-jp-work 1355] Modified: head/ja_JP.eucJP/articles/problem-reports/article.xml Modified: head/ja_JP.eucJP/articles/problem-reports/article.xml ============================================================================== --- head/ja_JP.eucJP/articles/problem-reports/article.xml Fri Dec 28 13:01:41 2012 (r40487) +++ head/ja_JP.eucJP/articles/problem-reports/article.xml Fri Dec 28 15:02:30 2012 (r40488) @@ -7,13 +7,13 @@ <!-- The FreeBSD Japanese Documentation Project - Original revision: r19282 + Original revision: r20986 $FreeBSD$ --> <article lang='ja'> <articleinfo> - <title>FreeBSD 障害報告の書き方</title> + <title>&os; 障害報告の書き方</title> <legalnotice id="trademarks" role="trademarks"> &tm-attrib.freebsd; @@ -27,7 +27,7 @@ <abstract> <para>この記事では、明瞭な障害報告 (Problem Report: PR) を - FreeBSD プロジェクトに提出する方法を解説します。</para> + &os; プロジェクトに提出する方法を解説します。</para> </abstract> <authorgroup> @@ -63,7 +63,7 @@ 上手な障害報告とは、迅速に解析を進め処理を行うことができ、 利用者と開発者がお互いに満足できるものです。</para> - <para>この記事では主として FreeBSD の障害報告に焦点を絞っていますが、 + <para>この記事では主として &os; の障害報告に焦点を絞っていますが、 他のソフトウェアプロジェクトでも多くの部分が当てはまるでしょう。</para> <para>この記事はテーマ別に整理されており、順番に読めるようにはなっていません。 @@ -140,7 +140,11 @@ 何が悪いのかわかる可能性もありません。 これはバグが起こらなかったことを意味するわけではありません。 しかし、このような状況ではあなたの障害報告がバグの修正に - つながる見込みは非常に薄く、報告をやめることを検討すべきです。</para> + つながる見込みは非常に薄いものです。 + おまけに、この手のバグは実際は故障したハードディスクや過熱した + CPU が原因で起きていることが多いのです + (障害報告を提出する前には必ず、可能なら、 + こうした原因を排除するよう努めるべきです)。</para> </section> <section id="pr-prep"> @@ -154,11 +158,11 @@ あなたが動かしているものより新しいバージョンで、 既に修正済みということすらありえます。 ですから、障害報告を提出する前に自明な場をすべて確認すべきです。 - FreeBSD については、以下のところになります。</para> + &os; については、以下のところになります。</para> <itemizedlist> <listitem> - <para>FreeBSD の + <para>&os; の <ulink url="../../books/faq/index.html">よくある質問とその答え</ulink> (FAQ) 一覧。 FAQ は、 @@ -174,7 +178,7 @@ url="../../books/handbook/eresources.html#ERESOURCES-MAIL"> メーリングリスト</ulink>。 — メーリングリストを購読していなければ、 - FreeBSD のウェブサイトにある + &os; のウェブサイトにある <ulink url="http://www.FreeBSD.org/ja/search/search.html#mailinglists">; アーカイブ検索</ulink>を使ってください。 @@ -195,35 +199,50 @@ <listitem> <para>次に、検索可能な <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">; - FreeBSD 障害報告データベース</ulink> (GNATS) があります。 + &os; 障害報告データベース</ulink> (GNATS) があります。 あなたの問題が新しいものでも不明瞭でもなければ、 既に報告されている可能性がかなり高いです。</para> </listitem> <listitem> - <para>最後に、 - もしもあるバージョンから別のバージョンにアップグレードしようとしているのであれば - (特に <literal>-current</literal> ブランチに上げようとしているなら)、 - システムの <filename>/usr/src/UPDATING</filename> ファイルの内容か、 + <para>何よりもまず、 + 元となるソースコード内のドキュメントで、 + あなたの問題が触れられていないか調べてみるべきです。</para> + + <para>&os; の基本部分のコードについては、 + システムの <filename>/usr/src/UPDATING</filename> ファイルの内容か、 <ulink url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>; - にある最新版をよく調べておきましょう。 - このファイルは非常に重要な情報を多く含んでいます。</para> + にある最新版をよく調べるべきです + (あるバージョンから別のバージョンにアップグレードしようとしているのであれば + —特に + <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>まず、問題がサードパーティソフトウェアのバグであれば、 - 原作者に報告すべきです。 - そうでなければ、FreeBSD プロジェクトに報告してください。 + <para>まず、問題がサードパーティソフトウェア + (あなたがインストールした port または package) + のバグであれば、原作者に報告すべきで、&os; + プロジェクトに報告すべきではありません。 このルールには二つの例外があります。 一つ目は、バグが他のプラットフォームで発生しない場合です。 - この場合は、FreeBSD への移植に原因がある可能性があります。 + この場合は、&os; への移植に原因がある可能性があります。 二つ目は、原作者がバグを既に修正していて、 そのソフトウェアの新しいバージョンかパッチを公開しているのに、 - FreeBSD の port がまだ更新されていない場合です。</para> + &os; の port がまだ更新されていない場合です。</para> - <para>それから、FreeBSD のバグ追跡システムは + <para>それから、&os; のバグ追跡システムは 発信者が選択した分類に従って 障害報告を分別しているということに注意してください。 もし間違った分類を選択した場合、あなたが送った障害報告は @@ -234,7 +253,7 @@ <title>障害報告の書き方</title> <para>問題が障害報告を行うに値すると結論を出し、 - そしてそれが FreeBSD の問題点であると判断したら、 + そしてそれが &os; の問題点であると判断したら、 実際に障害報告を執筆する時です。 障害報告を作成して送信するプログラムの仕組みに入る前に、 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。</para> @@ -287,31 +306,105 @@ <para><emphasis>あなたがメンテナなら、そう書いてください。</emphasis> ソースコードの一部 (たとえば、ある port) をメンテナンスし ているなら、概要行の先頭に - <literal>[maintainer update]</literal> という文字列をいれたり、 - 障害報告の <quote>Class</quote> を - <literal>maintainer-update</literal> にすることを検討してください。 - こうすれば、committer がその障害報告を扱う際に、 - いちいち確認する必要がありません。</para> - <!-- この部分は、rev.1.29 の変更を先取りしている。 --> + <literal>[maintainer update]</literal> + という文字列をできればいれて、障害報告の + <quote>Class</quote> を必ず + <literal>maintainer-update</literal> + にしてください。こうすれば、committer + がその障害報告を扱う際に、いちいち確認する必要がありません。</para> </listitem> <listitem> <para><emphasis>具体的に書いてください。</emphasis> あなたが抱えている問題について多くの情報を出すほど、 - 回答してもらえる可能性は高くなります。 - 動かしているバージョンは何か - (これを記載する場所があります。後述します)、 - どのアーキテクチャで動かしているのか、 - リリースの CDROM から入れたものか、 - それとも &man.cvsup.1; でメンテナンスしているシステムなのか - (そうだとしたら、最後に更新したのはいつか)、 - カーネルの問題なら <literal>src/UPDATING</literal> は読んだのか - (間違いなく聞かれます) といったことを盛り込むべきです。 - カーネルコンフィグレーションや、どの ports - が利用できるのかということや、コアダンプをつける必要はありませんが - (無条件でそれらを添付するのは、 - 単にデータベースを一杯にするだけになりがちです)、 - 要求されたら非公開か公開どちらかで出せるように準備しておきましょう。</para> + 回答してもらえる可能性は高くなります。</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> @@ -368,8 +461,8 @@ &man.send-pr.1; は障害報告の提出と追跡にメールを利用します。 &man.send-pr.1; を動かすマシンからメールを送ることができないと、 あなたの障害報告は GNATS データベースに届きません。 - FreeBSD におけるメールの設定の詳細については - FreeBSD ハンドブックの <quote>電子メール</quote> の章 + &os; におけるメールの設定の詳細については + &os; ハンドブックの <quote>電子メール</quote> の章 <ulink url="http://www.freebsd.org/doc/ja_JP.eucJP/books/handbook/mail.html"></ulink>; をご覧ください。</para> </section> @@ -395,11 +488,12 @@ 使って作成してください (unified 形式の方が好まれます)。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 - 修正したファイルの正確な CVS のリビジョン番号が特定できるか確認してください。 - 新しいコードはすべて CVS の CURRENT または - HEAD ブランチにあててテストするべきなので、 - それに対するパッチが望ましいです。適切か十分なテストが行なわれたら、 - そのコードは STABLE ブランチにマージまたは移植されます。</para> + 修正したファイルの正確な CVS のリビジョン番号が特定できるか確認してください。 + カーネルやベースのユーティリティに関しては、新しいコードはすべて + &os.current; (CVS の HEAD ブランチ) + でテストするべきなので、それに対するパッチが望ましいです。 + 適切か十分なテストが行なわれたら、そのコードは + &os.stable; ブランチにマージまたは移植されます。</para> <para>パッチを添付するのではなく本文中に含める場合、 もっともありがちな問題は、 @@ -457,7 +551,7 @@ <listitem> <para><emphasis>Submitter-Id (提出者-Id):</emphasis> これは変更しないでください。 - あなたが FreeBSD-STABLE を動かしている場合でも、既定値である + あなたが &os.stable; を動かしている場合でも、既定値である <literal>current-users</literal> が正しいのです。</para> </listitem> @@ -487,7 +581,7 @@ <listitem> <para><emphasis>Confidential (機密):</emphasis> これは <literal>no</literal> で既に埋められています。 - 機密扱いの FreeBSD 障害報告というものはないため、 + 機密扱いの &os; 障害報告というものはないため、 変更することに意味はありません。— 障害報告データベースは <application>CVSup</application> によって、 世界的に配布されています。</para> @@ -503,7 +597,7 @@ <para>上述したように、障害報告にパッチが含まれているなら、 概要の先頭に <literal>[patch]</literal> と書いて下さい。 あなたがメンテナなら、 - <literal>[maintainer update]</literal> を追加したり、 + <literal>[maintainer update]</literal> を追加して、 障害報告の <quote>Class</quote> を <literal>maintainer-update</literal> にするようにしてください。</para> @@ -518,9 +612,16 @@ あなたの問題が本当に致命的 (たとえば、 <username>root</username> 権限を悪用できたり、 パニックを容易に再現できるなど) でない場合は、 - <literal>critical</literal> に分類するのは控えてください。 - 障害報告を提出する人達は自分の問題を大げさに評価しがちであり、 - そのため開発者はこのフィールドや次のフィールドを無視する傾向があります。</para> + <literal>critical</literal> + に分類するのを、また多くの人に影響するのでなければ + (特定のデバイスドライバやシステムユーティリティ)、 + <literal>serious</literal> + に分類するのを控えてください。 + まったく同じことをやった人があまりに多いため、 + 問題の重要性を水増ししても、必ずしも + &os; 開発者がその問題に早くとりかかるわけではありません。 + — 実際、 + それが理由でこのフィールドや次のフィールドにほとんど注意を払わない開発者もいます。</para> </listitem> <listitem> @@ -528,16 +629,21 @@ <literal>low (低い)</literal>、 <literal>medium (中間)</literal>、 <literal>high (高い)</literal> のどれかです。 - 分類の基準は前述していますので、読んでください。</para> + <literal>high (高い)</literal> + は実質的にすべての &os; ユーザに影響するもの、 + <literal>medium (中間)</literal> + は多くのユーザに影響するものに限定すべきです。</para> </listitem> <listitem> <para><emphasis>Category (分類):</emphasis> - 以下から一つを選んでください:</para> + 以下から一つを選んでください ( + <filename>/usr/gnats/gnats-adm/categories</filename> + からもってきています)。</para> <itemizedlist> <listitem> <para><literal>advocacy:</literal> - FreeBSD の世間的なイメージに関する問題。 + &os; の世間的なイメージに関する問題。 めったに使われません。</para> </listitem> @@ -589,7 +695,8 @@ <listitem> <para><literal>kern:</literal> - カーネルに関する問題。</para> + カーネルまたは (特定のプラットフォーム用ではない) + デバイスドライバに関する問題。</para> </listitem> <listitem> @@ -619,8 +726,14 @@ </listitem> <listitem> + <para><literal>threads:</literal> + &os; のスレッド実装 (特に &os.current; 上のもの) + に関する問題。</para> + </listitem> + + <listitem> <para><literal>www:</literal> - FreeBSD ウェブサイトへの変更と改善。</para> + &os; ウェブサイトへの変更と改善。</para> </listitem> </itemizedlist> </listitem> @@ -658,7 +771,7 @@ <listitem> <para><emphasis>Release:</emphasis> - あなたが動作させている FreeBSD のバージョン。 + あなたが動作させている &os; のバージョン。 これは &man.send-pr.1; によって自動的に書き込まれますが、 あなたが障害が起きているものと違うシステムから障害報告を送信する場合に限り、 変更する必要があります。</para> @@ -745,11 +858,42 @@ 誰かがあなたの障害報告を審査追跡状態にして、 何らかのコメントかパッチの通知を自動的に受けとるでしょう。</para> - <para>誰かがあなたにさらなる情報を求めたり、 + <para>誰かがあなたに追加情報を求めたり、 最初の報告の中で言及しなかったものを思い出したり発見したら、 - バグ追跡システムがどの障害報告に結びつければよいか知るために、 - 件名に追跡用の数字が含まれているかを確かめて - <email>bug-followup@FreeBSD.org</email> にメールを送ってください。</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>または、 + バグ追跡システムがどの障害報告に加えればよいか判断できるように、 + 件名に追跡番号が含まれているか確かめて + <email>bug-followup@FreeBSD.org</email> + にメールを送るだけでも構いません。</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>問題がなくなったのに障害報告の処理が完了していなければ、 できれば、どのように、いつ、問題を解決できたかの説明を添えて、 @@ -771,14 +915,14 @@ (<ulink url="http://www.unixuser.org/~ueno/bugs-ja.html">; 日本語訳</ulink>) — - Simon G. Tatham 氏による、(FreeBSDに限らない) + Simon G. Tatham 氏による、(&os; に限らない) 役に立つ障害報告の作成についてのすぐれたエッセイ。</para> </listitem> <listitem> <para><ulink url="../../../en_US.ISO8859-1/articles/pr-guidelines/article.html"> 障害報告 取り扱いガイドライン</ulink> — - 障害報告が FreeBSD の開発者によってどのように + 障害報告が &os; の開発者によってどのように 扱われるかについて有益な見識をまとめた記事。</para> </listitem> </itemizedlist>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201212281502.qBSF2Vrb046871>