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

English version is HowToReport.

簡単な手順

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

  1. 最新版で試してみる。
    • もしあなたが ruby 1.9.2-p0 など古いリリースを使っている場合、最新パッチリリースを入れて試してみる。バグフィクスなどをしたメンテナンスリリースなどを使えば仕様変更の心配はありません。
  2. 以下を準備する。
    • 再現手順 (特に再現コード)
    • ruby -v の結果
    • 実際に起きた結果
      • 実行時のログ。
      • OSX の場合、プログラムがクラッシュしたときに ~/Library/Logs/CrashReporter もしくは /Library/Logs/CrashReporter にログが出力されるので、可能であれば用意する。
      • ただし Ruby 自体がクラッシュしていない場合などには存在しません。[BUG] などと書かれて Ruby が終了した場合は Ruby 自体がクラッシュしています。
    • 期待した結果
      • 例) この例外は起きないべきだ
      • 例) ここでこの例外が起きるべきだ
  3. 以下のページを開き、New Issues をクリックする。
    • trunk で再現するバグを報告する場合: ruby-trunk に登録する。
    • リリースされたバージョン (2.1、2.0.0、1.9.x) で再現するバグを報告する場合: ruby-trunk に登録する。個別バージョンのプロジェクトでバグ報告をする必要はない(できない)。
    • 1.8 でのみ再現するバグを報告する場合: Ruby 1.8 に登録する。
  4. フォームを埋めて登録する。
    • Tracker: 通常は "Bug" report を選ぶ。仕様変更を要求する場合は "Feature" request だが、バグとは異なるレベルで議論が行われるので HowToRequestFeatures を参照のこと。
    • field_mailing_list: 英語 or 日本語を選ぶ。
    • Subject: 問題を最大 60 文字程度で書く。
    • Description: (1) で準備したものを簡潔に書く。自然言語は 140 字に収まる程度だとよい。
      • 再現スクリプト・OSX のクラッシュレポート・実行時のログなど、あまりに長大なものについては、添付ファイルとするのがよい。
    • Status と Priority はそのまま。なお、焦って Priority を High などとあなたの判断で指定することは、あまりいい印象を抱かれません。
    • ruby -v: ruby -v の結果をそのまま貼りつける。
    • 他は適当に。よくわからなければそのままでも構いません。
  5. 気長に見守る。
    • 10 日程度反応がなければ、見過ごされている可能性が高いので催促しても構いません。
    • feedback を求められたら答えてください。feedback に状態が変更されて数ヶ月たつと reject される場合が多いです。
    • reject されても泣かない。

より確実な・間違いがなさそうなバグ報告をしたい方は下記もご覧下さい。

よりよい報告の手順

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

よりよい報告のための tips

Ruby 特有の話

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

バグ報告一般の話

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

参考: よくある誤った / すでに解決済みのバグ報告

注意事項

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

関連文書