[ruby-dev:42594] Re: Rubyのバグレポートのガイドライン

遠藤です。

2010年11月18日11:48 Shota Fukumori (sora_h) <[e-mail]>:
> 元を書いてくれたmame3の様子をみてドラフトを外してみようかと思います。
> 誰か英語版のproofreadを行っていただけないかなあ。


バグ報告というのは、多少情報が不足していようと不備があろうと、まずは
「報告してもらうこと」が一番大事です。なので、こういうガイドラインは
バグ報告しやすい雰囲気を醸しだすべく、なるべく報告者にやさしいものを
目指すべきだと思います。

不備のあるチケットがたくさん登録されるとチケット管理の面で困るという
意見もあるかもですが、注意書きで厳しいこと書いたところで、

  - ダメなチケットを登録する人はどうせ読まない
  - まともなチケットを登録してくれるはずの人をビビらせてしまう

という感じに、いいことないと思います。


そのため、初期のドラフトは以下の指針で書いていたつもりでした。

  - 全体的に記述を短くする
  - 必須項目は最小限にする
  - 推奨項目は推奨であることを明示する
  - でも覚悟しておいてほしいことは書く

現在の版は開発者よりの記述になっていて、報告者にいろいろ要求しすぎだ
と思います。なので、個人的にはやや否定的です。

例えば、「再現コード」は必須ですが、「最小の再現コード」は推奨レベル
だと思います。「Ruby に報告すべきバグかどうか判断せよ」「修正済みで
ないか調べろ」というのは要求しすぎです。
自分が部外者なら自信がもてなくて報告を控えてしまいます。


というわけで、大幅に書き換えてみました。でもまだ多い気もする。




= Ruby バグレポートガイドライン

((*English version is [[HowToReport]].*))

((*このガイドラインはドラフトです。*))

== 簡単な手順

((*security issue (脆弱性等) を報告する場合は非公開ML [e-mail] にメールを送ること*))

(1) 以下を準備する。
    * 再現手順 (特に再現コード)
    * ruby -v の結果
    * 実際に起きた結果
    * 期待した結果
(2) 以下のページを開き、New Issues をクリックする。
    * 1.9 で再現するバグを報告する場合: [[Ruby 1.9:]]
    * 1.8 と 1.9 の両方で再現する場合: [[Ruby 1.9:]] に登録し、1.8 でも再現した旨を記す。
    * 1.8 で再現するバグを報告する場合: [[Ruby 1.8:]]
(3) フォームを埋めて登録する。
    * Tracker: 通常は "Bug" report か "Feature" request を選ぶ。
    * field_mailing_list: 英語 or 日本語を選ぶ。
    * Subject: 問題を最大 60 文字程度で書く。
    * Description: (1) で準備したものを簡潔に書く。自然言語は 140 字に収まる程度だとよい。
    * Status と Priority はそのまま。
    * ruby -v: ruby -v の結果をそのまま貼りつける。
    * 他は適当に。よくわからなければそのままでも構いません。
(4) 気長に見守る。
    * 10 日程度反応がなければ、見過ごされている可能性が高いので催促しても構いません。
    * feedback を求められたら答えてください。
    * reject されても泣かない。

== よりよい報告の手順

(1) 軽く下調べする
    * 似た報告がないか簡単に検索する (Google 程度で OK)
    * 可能なら trunk など最新ブランチで再現するか調べる
(2) 以下を準備する
    * 再現手順 (特に小さな再現コード)
      * なるべく短くて外部ライブラリを使わないコードだとよい
      * 再現コードで gem を使っている場合は、再現手順に gem install foo などと書いてください。
    * ruby -v の結果
    * 実際に起きた結果
      * 実行ログを全部貼り付ける。むやみに省略しない。
    * 期待した結果と、それを期待した理由
      * 理由の例: rdoc に書いてある、旧バージョンでは期待通りに動いた、他の挙動から類推した、etc.
    * この問題の重要さ
      * 例: 影響を受けるライブラリ名を挙げる、影響を受けるユースケースを示す、回避策がない、etc.
    * 使用したコンパイラとそのバージョン
    * デバッガのバックトレース (異常終了する場合)
    * gem list や gem env の結果 (gem を使用している場合)
    * 自分でソースからビルドした場合は、configure に与えたオプション
    * その他、独自の考察やパッチがあればそれも
(3) フォームを開いて埋める。(「簡単な手順」を参照)
(4) 気長に見守る。
    * reject の理由に納得がいかなかったら、反論するといいです。ただし reject の理由をきちんと理解した上で。
      * 良い例) 「軽微な問題なので対応しない」という reject に対して「問題の重大さ」を説く
      * 悪い例) 「メンテナ不在のため対応不能」という reject に対して「問題の重大さ」を説く
      * 悪い例) 「仕様の変更」という reject に対して「問題の重大さ」を説く
    * 「バグではない」と言われた場合は、仕様変更にならない形で Feature request として再登録することを検討する
    * 「互換性維持のために修正不能」と言われた場合は、Ruby 2.0 の仕様策定の機会を伺う
    * 「メンテナ不在のため対応不能」と言われた場合は、自分でパッチを書くか、書いてくれる人を探す・雇う
(5) 「修正した」と言われたら、修正されていることを確認する。
    * preview リリースや RC リリースが出たら、再度確認する

== よりよい報告のための tips

Ruby 特有の話

* trunk の取得方法: ((<レポジトリガイド|URL:http://www.ruby-lang.org/ja/documentation/repository-guide>))を参照。svn
が使えないなら((<スナップショット|URL:http://www.ruby-lang.org/ja/downloads/>))を使うと良い。
* gdb でのバックトレースの取り方: ((%gdb --args ruby foo.rb%)) で起動し、((%run%))
で実行し、落ちたら ((%bt%)) を実行する。
* rvm を使わずにテストする (rvm 側の問題と切り分けるため)
* ユニットテストを書けると良い (必須ではない。test/ 以下を参考に)
* パッチを書いた場合は ((%make update-rubyspec ; make test-rubyspec ; make
check%)) を確認する (詳しくは [[DeveloperHowtoJa]] を参照) 。

バグ報告一般の話

* 本当にバグか今一度考える
  * 「自分の直感に合わない」という主観は大切ですが、客観的な事実も書いた方が通じやすい
  * rdoc や((<るりま|URL:http://doc.ruby-lang.org/ja/>))を参照して、仕様を確認する
  * 自信が持てない場合は、登録前に ML や IRC で聞いてみるとよい
     * ((<IRCとMLのリスト|URL:http://www.ruby-lang.org/ja/community>)) を参考に参加してみる
* 過去に報告済みでないか、検索等で簡単に調べる
* 1 つのバグ報告では 1 つのバグだけを報告する
* 必要十分な情報を簡潔に書く
* 再試するための情報がすべて載っていることを確認する

== 参考: よくある誤ったバグ報告
  * 小数計算の結果がおかしい
    * 浮動小数点数の計算には誤差があります。参考サイト:
((<1|URL:http://docs.sun.com/source/806-4847/ncg_goldberg.html>))
((<2|URL:http://wiki.github.com/rdp/ruby_tutorials_core/ruby-talk-faq#floats_imprecise>))
((<3|URL:http://en.wikipedia.org/wiki/Floating_point#Accuracy_problems>))
  * String#gsub で \ (円マーク・バックスラッシュ) に置換しようとしたら何かおかしい
    * 仕様です。((<String#gsub|URL:http://doc.okkez.net/static/192/method/String/i/gsub.html>))
を参照。

== 注意事項

* このガイドラインは、バグ報告者と開発者のコミュニケーションを円滑にし、バグ報告と修正を効率的かつ円満に進めるためのものです。
* バグ報告者はこれに従う義務はありませんが、なるべく従うことを推奨します。特に「簡単な手順」の 1 は、バグ修正のために事実上必須です。
* バグ報告がこのガイドラインに従っていないというだけで reject
されることはありません。ただし、情報が足りないバグ報告に対して、このガイドラインを指示・引用して feedback
をお願いすることはあります。
* このガイドラインが常に適切とは限りません。適切でないと思う場合は更新してください。(更新する前に ruby-dev (日本語) か
ruby-core (英語) で議論するとよいです)

== 関連文書

* ((<効果的にバグを報告するには (日本語)|URL:http://www.unixuser.org/~ueno/bugs-ja.html>))
* ((<How to Report Bugs Effectively
(英語)|URL:http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>))
* ((<mozilla's Bug writing guidelines
(日本語)|URL:https://developer.mozilla.org/ja/Bug_writing_guidelines>))
* ((<mozilla's Bug writing guidelines
(英語)|URL:https://developer.mozilla.org/en/Bug_writing_guidelines>))
* ((<やさしいバグトラッキング
(日本語)|URL:http://japanese.joelonsoftware.com/Articles/PainlessBugTracking.html>))
* ((<Painless Bug Tracking
(英語)|URL:http://www.joelonsoftware.com/articles/fog0000000029.html>))

-- 
Yusuke Endoh <[e-mail]>