From owner-svn-doc-head@FreeBSD.ORG Sun Oct 28 15:25:50 2012 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 3C77EB38; Sun, 28 Oct 2012 15:25:50 +0000 (UTC) (envelope-from ryusuke@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 21BC08FC08; Sun, 28 Oct 2012 15:25:50 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q9SFPoj6037204; Sun, 28 Oct 2012 15:25:50 GMT (envelope-from ryusuke@svn.freebsd.org) Received: (from ryusuke@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q9SFPoG1037202; Sun, 28 Oct 2012 15:25:50 GMT (envelope-from ryusuke@svn.freebsd.org) Message-Id: <201210281525.q9SFPoG1037202@svn.freebsd.org> From: Ryusuke SUZUKI Date: Sun, 28 Oct 2012 15:25:50 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39826 - head/ja_JP.eucJP/articles/problem-reports X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 28 Oct 2012 15:25:50 -0000 Author: ryusuke Date: Sun Oct 28 15:25:49 2012 New Revision: 39826 URL: http://svn.freebsd.org/changeset/doc/39826 Log: - Merge the following from the English version: r16288 -> r19282 head/ja_JP.eucJP/ja_JP.eucJP/articles/problem-reports/article.xml Submitted by: Hiroo Ono References: [doc-jp-work 997, 1302] 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 Sun Oct 28 00:58:36 2012 (r39825) +++ head/ja_JP.eucJP/articles/problem-reports/article.xml Sun Oct 28 15:25:49 2012 (r39826) @@ -7,7 +7,7 @@ @@ -15,6 +15,16 @@ FreeBSD 障害報告の書き方 + + &tm-attrib.freebsd; + &tm-attrib.cvsup; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.sun; + &tm-attrib.general; + + この記事では、明瞭な障害報告 (Problem Report: PR) を FreeBSD プロジェクトに提出する方法を解説します。 @@ -70,11 +80,11 @@ それらすべてが障害報告に値するというわけではありません。 もちろん、誰しもが完璧ではありませんので、 実際はコマンドの構文を勘違いしていたり、 - 設定ファイルに書き間違いをしている場合などを + 設定ファイルを書き間違えているのに、 プログラムにバグを見つけた! と思い込んでしまうことがあるでしょう (とは言っても、それ自身、文書が適切に記述されていなかったり、 アプリケーションのエラー処理が甘いことを暗示している可能性があります)。 - それ以外にも、障害報告を提出することが正しい行動ではなく、 + それ以外にも、障害報告を提出することが正しい行動ではなく、 あなたや開発者たちをただ 不満にさせるためだけに作用してしまう場合があります (訳注: はっきりと把握していないことを報告すべきではありません。 @@ -152,7 +162,14 @@ - FAQ を調べる。 + FreeBSD の + よくある質問とその答え + (FAQ) 一覧。 + FAQ は、 + ハードウェア互換性、 + ユーザアプリケーション や + カーネルコンフィグレーション + といったことに関する広い範囲の質問に対して答を示そうとしています。 @@ -181,9 +198,21 @@ - 最後に、FreeBSD 障害報告データベースを調べる。 - あなたの問題が新しいものでなかったり不明瞭であれば、 - 既に報告されている可能性がかなりあります。 + 次に、検索可能な + + FreeBSD 障害報告データベース (GNATS) があります。 + あなたの問題が新しいものでも不明瞭でもなければ、 + 既に報告されている可能性がかなり高いです。 + + + + 最後に、 + もしもあるバージョンから別のバージョンにアップグレードしようとしているのであれば + (特に -current ブランチに上げようとしているなら)、 + システムの /usr/src/UPDATING ファイルの内容か、 + + にある最新版をよく調べておきましょう。 + このファイルは多くの非常に重要な情報を含んでいます。 @@ -212,11 +241,143 @@ 自分の問題が障害報告を行うに値すると結論を出し、 そしてそれが FreeBSD の問題点であると判断したのですから、 実際に障害報告を執筆する時です。 - 環境変数 VISUAL - (か、もし VISUAL - が設定されていなければ EDITOR) - が何らかの使える値に設定されているか確認して、 - &man.send-pr.1; を実行します。 + 障害報告を作成して送信するプログラムの仕組みに入る前に、 + 障害報告をもっとも効果的なものにするこつをいくつか紹介しましょう。 + +
+ よい障害報告を書くこつ + + + + Synopsis(概要) + 行を空のままにしないでください。 + 障害報告は、世界中に配布されるメーリングリストに送られる + (そこでは、Synopsis (概要) は + Subject: 行に使われます) と共に、 + データベースにも入れられます。後でデータベースを synopsis (概要) + で参照する人は、題がついていない障害報告は単に無視することでしょう。 + このデータベースに登録された障害報告は、 + 誰かが閉じるまでは残っていることを忘れないでください。 + 内容不明のものは大抵雑音に埋もれてしまいます。 + + + + わかりにくいSynopsis (概要) + 行は避けましょう。 + あなたが提出した障害報告を読む人がどういう状況か分かっていると仮定すべきではありません。 + できるだけ詳しく書きましょう。 + たとえば、その問題はシステムのどの部分にあてはまるのでしょうか。 + インストール中にしか問題に当たらないのか、それとも稼働中に当たるのか。 + 具体的な例でいうなら、Synopsis: portupgrade is broken + (概要: portupgrade がおかしい) ではなく、 + 次のように書いたらどれだけ伝わりやすいか考えてみてください。 + Synopsis: port sysutils/portupgrade coredumps on + -current (概要: sysutils/portupgrade port が + -current でコアダンプします)。(ports の場合は、 + Synopsis (概要) 行に分類と名前を入れると、 + とても助かります)。 + + + + パッチがあるなら、そう書いてください。 + パッチがついている障害報告は、 + ついていないものよりも見てもらえる可能性が高いです。パッチをつける場合は、 + Synopsis (概要) 行の先頭に + [patch] という文字列をいれて下さい。 + (この通り書かなければならないというわけではありませんが、 + 慣習としてこの文字列が用いられています)。 + + + + あなたがメンテナなら、そう書いてください。 + ソースコードの一部 (たとえば、ある port) をメンテナンスし + ているなら、概要行の先頭に + [maintainer update] という文字列をいれたり、 + 障害報告の Class を + maintainer-update にすることを検討してください。 + こうすれば、committer がその障害報告を扱う際に、 + いちいち確認する必要がありません。 + + + + + 具体的に書いてください。 + あなたが抱えている問題について多くの情報を出すほど、 + 回答してもらえる可能性は高くなります。 + 動かしているバージョンは何か + (これを記載する場所があります。後述します)、 + どのアーキテクチャで動かしているのか、 + リリースの CDROM から入れたものか、 + それとも &man.cvsup.1; でメンテナンスしているシステムなのか + (そうだとしたら、最後に更新したのはいつか)、 + カーネルの問題なら src/UPDATING は読んだのか + (間違いなく聞かれます) といったことを盛り込むべきです。 + カーネルコンフィグレーションや、どの ports + が利用できるのかということや、コアダンプをつける必要はありませんが + (無条件でそれらを添付するのは、 + 単にデータベースを一杯にするだけになりがちです)、 + 要求されたら非公開か公開どちらかで出せるように準備しておきましょう。 + + + + 漠然と機能を要求するのはやめましょう。 + 誰かこういうことするものを実装すべきだ + という形の障害報告は、詳細な要望に比べて成果を得にくいものです。 + ソースコードは誰でも利用できるのですから、何か機能が欲しければ、 + それをいれる最善の手段は作業にとりかかることです。 + また上述したように、こういうことは多くの場合、 + 障害報告データベースに登録するよりも + freebsd-questions で議論した方がよいでしょう。 + + + + 誰かが既に似たような障害報告を提出していないか確認してください。 + これは、既に述べたことではありますが、ここで繰り返しておくに値するでしょう。 + Web ベースの検索エンジン + + で調べるのは 1, 2 分程度しかかかりません。 + (もちろん、誰もがときどきこれを忘れてしまうという罪を犯しています)。 + + + + 異論のある要望は出さないようにしましょう。 + あなたの障害報告がかつて論争になった分野に関するものであったら、 + パッチを提出するだけでなく、そのパッチが + 正当なものである 根拠も提出したほうがよいかもしれません。 + どの場合でも上述のように + + でメーリングリストのアーカイブを検索して備えるのはよいことでしょう。 + + + + 礼儀正しくしましょう。 + あなたの障害報告について作業する人は、 + ほとんど全員がボランティアです。 + 金銭的収入以外の動機から行なっていることを、 + やれと命令されるのは誰も好きではありません。 + オープンソースプロジェクトに関しては、 + これを常に念頭においておくとよいでしょう。 + + +
+ +
+ 始める前に + + &man.send-pr.1; プログラムを動かす前に、環境変数 + VISUAL (もし VISUAL + が設定されていなければ EDITOR) + が意味のあるものに設定されているか確認しましょう。 + + また、メール配送ソフトウェアが正常に動作することも確認してください。 + &man.send-pr.1; は障害報告の提出と追跡にメールを利用します。 + &man.send-pr.1; を動かすマシンからメールを送ることができないと、 + あなたの障害報告は GNATS データベースに届きません。 + FreeBSD におけるメールの設定の詳細については + FreeBSD ハンドブックの 電子メール の章 + + をご覧ください。 +
パッチやファイルを添付する @@ -236,23 +397,29 @@ パッチは context 形式か unified 形式の差分を &man.diff.1; の か オプションを - 使って作成してください。 + 使って作成してください (unified 形式の方が好まれます)。 パッチを添付する場合、 開発者があなたの報告を読んで簡単にパッチを適用できるように、 - 修正したファイルの正確な CVS のリビジョン番号が特定できるか - 確認してください。 - - 一般的に、 - 障害報告の中に小さなパッチを含める分にはいいのですが、 - 記載される問題についての修正が大規模な場合や新しいコードの場合は - 十分な査読を行なった後にコミットすべきであるため、 - パッチを Web や FTP サーバに置き、その URL を障害報告に含めてください。 + 修正したファイルの正確な CVS のリビジョン番号が特定できるか確認してください。 + 新しいコードはすべて CVS の CURRENT または + HEAD ブランチにあててテストするべきなので、 + それに対するパッチが望ましいです。適切か十分なテストが行なわれたら、 + そのコードは STABLE ブランチにマージまたは移植されます。 + + パッチを添付するのではなく本文中に含める場合、 + もっともありがちな問題は、 + 電子メールプログラムによってはタブをスペースに変更してしまい、 + Makefile に含めるつもりだったものを台無しにしてしまうことです。 + + また、障害報告の中に小さなパッチを含めるのは + (とりわけ説明されている障害を修正する場合は) 大抵問題ないのですが、 + 大規模なパッチや新しいコードの場合は十分な査読を行なった後にコミットすべきであるため、 + パッチを Web や FTP サーバに置き、その URL を障害報告に書いてください。 電子メールに含めたパッチはサイズが大きいと分割される傾向にあり - (とりわけ Gnats が処理に関わるときはそうです)、 - 肝心な部分が変にならないように注意をはらってください。 - また、パッチに変更があった場合、 - 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくとも - Web から該当部分のパッチを送信して変更することができます。 + (とりわけ GNATS が処理に関わるときはそうです)、 + パッチが大きいほど興味をもった人がつなぎ直すのが面倒になります。 + また、Web にパッチをおけば、 + 元の障害報告へのフォローアップとしてパッチ全体を再提出しなくとも変更することができます。 また、障害報告かパッチ自体に明確に指定がなければ、 あなたが提出したパッチは修正した元のファイルと同じ条件の @@ -262,10 +429,10 @@
テンプレートに記入する - テンプレートは特定のフィールドから成り立っており、 - あらかじめ書き込まれた部分がいくつかあります。そこには - フィールドの目的が何かを説明する解説や - そのフィールドに利用可能な値が書かれています。 + &man.send-pr.1; を動かすとテンプレートが表示されます。 + テンプレートは特定の項目から成り立っており、 + その一部にはあらかじめ埋められていたり、 + その項目の目的の解説やそこに記入できる値の一覧が記載されていたりします。 コメントの部分は、自分で変更・削除しなくても、 自動的に削除されますので心配する必要はありません。 @@ -302,7 +469,7 @@ Originator (あなたの名前): これは普通、現在ログインしているユーザの - GECOS フィールドを使って既に埋められています。 + gecos フィールドを使って既に埋められています。 あなたの実際の名前を指定してください。 お好みで、名前の後ろに電子メールアドレスを 山括弧 (< と > のこと) で閉じて付けることができます。 @@ -340,7 +507,13 @@ 障害報告にパッチを添付する場合、概要の先頭に [PATCH] と書いてください。 - + 上述したように、障害報告にパッチが含まれているなら、 + 概要の先頭に [patch] と書いて下さい。 + あなたがメンテナなら、 + [maintainer update] を追加したり、 + 障害報告の Class を + maintainer-update にすることを検討してください。 + Severity (重要度): @@ -379,6 +552,11 @@ + amd64: + AMD64 プラットフォーム固有の問題。 + + + bin: 基本システムに含まれるユーザランドプログラムに関する問題。 @@ -401,7 +579,7 @@ i386: - i386 プラットフォーム固有の問題。 + &i386; プラットフォーム固有の問題。 @@ -411,7 +589,7 @@ java: - Java™ に関する問題。 + &java; に関する問題。 @@ -421,7 +599,8 @@ misc: - これらの分類に適合しないその他の分類。 + これらの分類に適合しないその他の分類 + (なお、ここに分類されると見失われやすいです)。 @@ -431,12 +610,12 @@ powerpc: - PowerPC プラットフォーム固有の問題。 + &powerpc; プラットフォーム固有の問題。 sparc64: - SPARC プラットフォーム固有の問題。 + &sparc64; プラットフォーム固有の問題。