History

How to report bugs in Ruby

This guide needs proofreading. 日本語版(Japanese version): HowToReportJa.

Simple steps

IMPORTANT: If the bug is security-related (security hole, vulnerability, etc.), Don't report it here. Please mail security@ruby-lang.org (Closed Mailing List)

  1. Try the latest version
    • If you aren't already using the latest version, try installing a newer stable release. See Downloading Ruby
  2. Prepare the following things
    • Reproducing steps; reproducing code is needed
    • Result of `ruby -v`
    • What you expected
    • What happened (If you have a error log, don't omit it.)
      • If Ruby crashed on OS X, you should have a crashlog under ~/Library/Logs/CrashReporter or /Library/Logs/CrashReporter. You should paste or attach it if available.
  3. Open the following page and click "New Issue".
    • If you're reporting a bug in Ruby 1.8 ONLY: Ruby 1.8
    • If you're reporting a bug in Ruby 1.9 ONLY: [[Ruby 1.9:]]
    • If you're reporting a bug in both Ruby 1.9 and Ruby 1.8: [[Ruby 1.9:]], and write like "this bug can be reproduced in Ruby 1.8 as well."
  4. Fill the form, then register it.
    • Preferred language: "English" or "Japanese"; Which language is your report written in?
    • Tracker: Usually select "Bug" or "Feature".
    • Subject: Write a summary of bug (or problem) in about 60 characters.
    • Description: Write the things in (2)
    • Status and Priority: Leave these alone.
    • ruby -v: Paste `ruby -v` result.
    • Assignee, Category, Target version, Start date, Due date, Estimated time, % Done: Leave these alone.
  5. Wait for reply
    • If ticket doesn't have any replies after 10 days, you can send a reminder.
    • Please reply to feedback requests. If a bug report doesn't get any feedback, it'll eventually get rejected.

More detailed steps for reporting

  1. Do some searching
    • Has the problem already been reported by someone? (Search in Google or Redmine)
    • Test the problem is reproducible in the trunk or maintenance branch
      • Is it already fixed?
  2. Prepare the following things
    • Reproducing steps (Smallest reproducing code)
      • The minimum amount of code possible is recommended.
      • If using a gem in reproducing code, write the "gem install" command in the reproduction steps.
    • Only supplying a log, or something like "On an xx test" won't lead to any action by developers.
    • ruby -v
    • What happened?
      • Don't omit running log or error log.
      • if Ruby crashed in OS X, you should have crashlog under ~/Library/Logs/CrashReporter or /Library/Logs/CrashReporter. You should paste or attach it if you have one.
    • What did you expect?, and why?
      • Example: It is written on RDoc, It works as might have been expected on an older version, etc.
    • What is the severity of the bug?
      • Example of a severe bug: A regression, segfault or build failure on a supported platform, or a bug that breaks a widely used gem.
      • Example of a less severe bug: A lack of consistency in an API, a bug that only occurs in a corner case, or a mild performance degredation.
    • Compiler version and compiler name
    • Backtrace on debugger
    • "gem list" and "gem env" if the reproducing steps includes gem
    • ./configure options
  3. Open form and fill it (See "Simple steps.")
  4. Wait for reply

Make better reports

Only on ruby

  • How to get trunk; See Repository guide. If you can't use svn, download snapshot.
  • How to take backtrace; Run gdb by gdb --args ruby foo.rb, Then type run, And type bt after ruby crashed.
  • Check that it's not an RVM bug.
    • Mention how you installed ruby. Did you install it from source, from a distribution package (which distribution?), ruby-installer,.. ?
    • If you installed Ruby using RVM try replicating the bug with Ruby installed by other means.
    • We used to get a lot of reports which were caused by RVM, not Ruby.
  • Write unit test on report; Refer under test/ directory
  • If you have written a patch, run make update-rubyspec ; make test-rubyspec ; make check and check tests passed; See DeveloperHowto on detail.

Generally

  • Is it really a bug?
    • Reference your claims.
    • Refer to RDoc or some document to check specification
    • If you aren't sure, ask in IRC or on the mailing list
  • Check if it is already reported by searching
  • Report one thing on one report
  • Write required things concisely.
  • Check that the report has enough information to reproduce the bug.

After it is fixed

  • Check it's fixed on next release.
  • Check it's fixed on preview release and RC release.

Points of this guide

  • This guide is used for making communication smoother between bug reporter and developers.
  • Bug reporter isn't needed to follow this guide always. But most important things are required for bug reporting.
  • Any reports won't be rejected if report doesn't follow this guide. But if report needs additional information, developer or someone requires following this guide.
  • This guide isn't always right. You can fix this guide when you think it isn't right. Discussing it on mailing-list ruby-core (English) or ruby-dev (Japanese) is recommended.

See also