ruby/doc/bug_triaging.rdoc

= Bug Triaging Guide

This guide discusses recommendations for triaging bugs in Ruby's bug tracker.

== Bugs with Reproducible Examples

These are the best bug reports.  First, consider whether the bug reported is
actually an issue or if it is expected Ruby behavior.  If it is expected Ruby
behavior, update the issue with why the behavior is expected, and set the
status to Rejected.

If the bug reported appears to be an actual bug, try reproducing the bug with
the master branch.  If you are not able to reproduce the issue on the master
branch, try reproducing it on the latest version for the branch the bug was
reported on.  If you cannot reproduce the issue in either case, update
the issue stating you cannot reproduce the issue, ask the reporter if they
can reproduce the issue with either the master branch or a later release,
and set the status to Feedback.

If you can reproduce the example with the master branch, try to figure out
what is causing the issue.  If you feel comfortable, try working on a
patch for the issue, update the issue, and attach the patch.  Try to figure
out which committer should be assigned to the issue, and set them as the
assignee, and set the status to Assigned.

If you cannot reproduce the example with the master branch, but can reproduce
the issue on the latest version for the branch, then it is likely the bug has
already been fixed, but it has not been backported yet.  Try to determine
which commit fixed it, and update the issue noting that the issue has been
fixed but not yet backported.  If the Ruby version is in the security
maintenance phase or no longer supported, change the status to Closed. This
change can be made without adding a note to avoid spamming the mailing list.

For issues that may require backwards incompatible changes or may benefit from
general committer attention or discussion, consider adding them as agenda
items for the next committer meeting (https://bugs.ruby-lang.org/issues/14770).

== Crash Bugs Without Reproducers

Many bugs reported have little more than a crash report, often with no way to
reproduce the issue.  These bugs are difficult to triage as they often do not
contain enough information.

For these bugs, if the Ruby version is the master branch or is the latest
release for the branch and the branch is in normal maintenance phase, look at
the backtrace and see if you can determine what could be causing the issue.
If you can guess what could be causing the issue, see if you can put together
a reproducible example (this is in general quite difficult).  If you cannot
guess what could be causing the issue, or cannot put together a reproducible
example yourself, please ask the reporter to provide a reproducible example,
and change the status to Feedback.

If the Ruby version is no longer current (e.g. 2.5.0 when the latest version
on the Ruby 2.5 branch is 2.5.5), add a note to the issue asking the reporter
to try the latest Ruby version for the branch and report back, and change the
status to Feedback.  If the Ruby version is in the security maintenance phase
or no longer supported, change the status to Closed. This change can be made
without adding a note.

== Crash Bugs With 3rd Party C Extensions

If the crash happens inside a 3rd party C extension, try to figure out inside
which C extension it happens, and add a note to the issue to report the
issue to that C extension, and set the status to Third Party's Issue.

== Non-Bug reports

Any issues in the bug tracker that are not reports of problems should have
the tracker changed from Bug to either Feature (new features or performance
improvements) or Misc. This change can be made without adding a note.

== Stale Issues

There are many issues that are stale, with no updates in months or even years.
For stale issues in Feedback state, where the feedback has not been received,
you can change the status to Closed without adding a note.  For stale issues
in Assigned state, you can reach out to the assignee and see if they can update
the issue.  If the assignee is no longer an active committer, remove them
as the assignee and change the status to Open.