HowToReportJa » History » Version 28

« Previous - Version 28/52 (diff) - Next » - Current version
ujihisa ., 11/17/2010 03:13 AM
consistency


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

((English version is HowToReport.))

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

((security issue (脆弱性等) の場合は非公開ML security@ruby-lang.org にメールを送ること))

== 要約

重要な部分は以下です。

より確実な報告をする場合は下記も参照ください。

報告の手順:

(1) 再現するなるべく最小のコード (外部ライブラリへの依存をできるだけ減らす) を書く
(2) バグがRubyに報告すべきバグかどうかを判断する

* [BUG]で落ちるはC拡張ライブラリのバグか、Ruby本体のバグかの2種類がある
* それ以外のバグは「ドキュメントとは違う動作」をする場合など
* Rubyのバグかどうかを確認する
* Cの拡張ライブラリを使用するライブラリを外すと再現しない、等はほぼ確実にライブラリのバグなのでRubyのバグではない
* ただしRubyに標準添付されている等ならRubyのバグ
* security issue (脆弱性等) の場合は非公開ML security@ruby-lang.org にメールを送ること
(3) そのバグが既に報告済・trunk, 該当バージョンのメンテナンスブランチで直っているかを確認する
* 直っているなら既に修正されている可能性がある
(4) 対応するプロジェクトのページを開き、New Issuesをクリック
* 日本語で報告する場合は上部のruby-coreやruby-devを日本語のruby-devに選択されていることを確認する
* メンテナが非日本語圏の場合は可能な限りruby-coreに英語で報告することが望ましい
* 作った最小コード、[BUG]などのエラーがある場合はそのログを全て (省略せずに) 貼り付ける
* 意図しない挙動などの場合は、挙動がおかしい事を示すログを貼り付ける
* 再現する手順に追加がある場合はそれも書く
* 自分のプラットフォーム (Windowsのバージョン、OSXのバージョン、Linuxのディストリビューション名など) を書くと尚良い
(5) 登録してじっと見守る
* 気長に待つ
* 場合によっては追加の事項のfeedbackを求められるかもしれない

== このガイドラインの主旨

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

== バグとは

  • ここでいうバグとは、Rubyのバグのことです
  • [BUG]で落ちるものはほぼ確実にRubyのバグですが、希に拡張ライブラリ (Cで拡張されたruby用ライブラリなど) のバグの事もあります
    • 後述する「最小のコード」で、拡張ライブラリを使用するライブラリを外すと [BUG] で落ちない、などなら拡張ライブラリのバグです。ライブラリ側に報告してください
    • ただし、そのライブラリが標準添付ならばRubyのバグです。一部のライブラリはupstreamがあるので、upstreamに報告する必要があるものもあります
  • また、標準添付ライブラリや組み込みのクラス・メソッドでの挙動がドキュメントとは違う、などといったものもバグとなります

== 絶対書くべきこと

(1) 再現する最小のコード + 再現手順
* 「最小のコード」とは、なるべくrequireするライブラリなどを減らし、確実に再現するコードの事を指す
* 悪い例) xxというソフトウェアのtestでSEGVする
(2) 実際に起きた結果
* [BUG]の後にログが出力された場合は、エラーログを全部貼り付ける
* 前半だけ貼られても原因を特定することができないことがあります。全部貼り付ける
(3) 期待した結果
* 例) この例外が発生するべきだ
* 例) 結果はこうなるべきだ
(4) ruby -v の結果
(5) 自分の環境 (Linuxであればディストリビューションとそのバージョン、WindowsであればWindowsのバージョン、Mac OS Xであればそのバージョンなど)
(6) 自分でソースからインストールした場合は、configureに与えたオプション、コンパイラのバージョンなど
(7) 外部のライブラリを使用している拡張ライブラリを使用している場合、その外部ライブラリのバージョンなど

備考

  • 自然言語は 140 文字程度に要約するといいです。
  • 再現コードは発生する最小の構成が理想ですが、大きくても無いよりは良いです。
  • 再現コードで gem を使っている場合は、再現手順に gem install foo などと書いてください。

== 書いておくとよいこと

(1) 問題が発生するバージョンとプラットフォームの詳細
* 特に trunk で起きるか否か
(2) その挙動を期待した理由
* 例: rdoc に書いてある、旧バージョンでは期待通りに動いた、他の挙動から類推した、etc.
(3) この問題の重要さ
* 例: 影響を受けるライブラリ名を挙げる、影響を受けるユースケースを示す、回避策がない、etc.
(4) 使用したコンパイラとそのバージョン
(5) デバッガのバックトレース (異常終了する場合)
(6) gem list や gem env の結果 (gem を使用している場合)
(7) パッチがあるならパッチを貼る
* git-svnなどを使っている場合は、 git diff --no-prefix でパッチを生成すると良い。

== 報告前にすべきこと

  • 最新のtrunkで直っているかどうかを確認する。
    • すでにfixされていて、次のパッチリリースで修正される予定があるものかもしれません。
  • すでに報告されているか確認する。
    • 同じような再現コードならば報告する必要はないと思われます。
    • 違う手順でも同じような事象が発生するなら報告を行って下さい。

== 具体的な報告方法 (redmine に登録する方法)

((重要: security issue となるおそれがある問題は、redmine に登録せず security@ruby-lang.org にメールを送信してください。))

(1) http://redmine.ruby-lang.org/ にログインする (アカウントがなければ登録する)
(2) 登録する project のページを開く
(3) new issue のフォームを開き、登録する

2 の project の選び方:
* 1.8 で再現した場合は Ruby 1.8 に登録する。
* 1.9 で再現した場合は [[Ruby 1.9:]] に登録する。
* 1.8 と 1.9 の両方で再現した場合は [[Ruby 1.9:]] に登録し、1.8 でも再現した旨を記す。
* その他のプロジェクト (Ruby 直下、Ruby 1.8.x 、Ruby 1.9.x 等) には登録しないでください。

3 のフォームの埋め方:
* Tracker: 通常は "Bug" report か "Feature" request を選ぶ。
* field_mailing_list: 英語 or 日本語を選ぶ。
* Subject: 問題を 60 文字程度で書く。
* Description: 「絶対書くべきこと」や「書いておくとよいこと」を書く。
* Status と Priority はそのまま。
* ruby -v: ruby -v の結果をそのまま貼りつける。
* 他は適当に。よくわからなければそのままでも構いません。

== 報告後にすること

  • 気長に待つ
    • しかし 10 日程度反応がなければ、見過ごされている可能性が高いので reminder を流すとよい
  • feedback (追加情報の提供) を求められたら返答する
    • 長期間 feedback がないチケットは reject されます
  • reject されても泣かない
  • reject の理由に納得がいかなかったら反論するとよいが、reject の理由をきちんと理解した上で反論する
    • 良い例) 「軽微な問題なので対応しない」という reject に対して「問題の重大さ」を説く
    • 悪い例) 「メンテナ不在のため対応不能」という reject に対して「問題の重大さ」を説く
    • 悪い例) 「仕様の変更」という reject に対して「問題の重大さ」を説く
  • 「バグではない」と言われた場合は、仕様変更にならない形で Feature request として再登録することを検討する
  • 「互換性維持のために修正不能」と言われた場合は、Ruby 2.0 の仕様策定の機会を伺う
  • 「メンテナ不在のため対応不能」と言われた場合は、自分でパッチを書くか、書いてくれる人を探す・雇う

必ずやるべきことでもないもの

  • IRCに報告する
    • %rubyなどではチケットの #1 などの番号を発言するだけでタイトルとURLがbotによって発言されます。
  • TwitterなどでチケットのURLを貼る

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

Ruby 特有の話

バグ報告一般の話

  • 本当にバグか今一度考える
  • 過去に報告済みでないか、検索等で簡単に調べる
  • 1 つのバグ報告では 1 つのバグだけを報告する
  • 必要十分な情報を簡潔に書く
  • 再試するための情報がすべて載っていることを確認する

== 修正後にするといいこと

  • 最新版で修正されていることを確認する
  • preview リリースや RC リリースが出たら、再度確認する

== 関連文書