(emacs)Understanding Bug Reporting

Next: Checklist Prev: Bug Criteria Up: Bugs

Understanding Bug Reporting

   When you decide that there is a bug, it is important to report it
and to report it in a way which is useful.  What is most useful is an
exact description of what commands you type, starting with the shell
command to run Emacs, until the problem happens.

   The most important principle in reporting a bug is to report *facts*,
not hypotheses or categorizations.  It is always easier to report the
facts, but people seem to prefer to strain to posit explanations and
report them instead.  If the explanations are based on guesses about
how Emacs is implemented, they will be useless; we will have to try to
figure out what the facts must have been to lead to such speculations.
Sometimes this is impossible.  But in any case, it is unnecessary work
for us.

   For example, suppose that you type `C-x C-f /glorp/baz.ugh RET',
visiting a file which (you know) happens to be rather large, and Emacs
prints out `I feel pretty today'.  The best way to report the bug is
with a sentence like the preceding one, because it gives all the facts
and nothing but the facts.

   Do not assume that the problem is due to the size of the file and
say, "When I visit a large file, Emacs prints out `I feel pretty
today'." This is what we mean by "guessing explanations".  The problem
is just as likely to be due to the fact that there is a `z' in the file
name.  If this is so, then when we got your report, we would try out
the problem with some "large file", probably with no `z' in its name,
and not find anything wrong.  There is no way in the world that we
could guess that we should try visiting a file with a `z' in its name.

   Alternatively, the problem might be due to the fact that the file
starts with exactly 25 spaces.  For this reason, you should make sure
that you inform us of the exact contents of any file that is needed to
reproduce the bug.  What if the problem only occurs when you have typed
the `C-x C-a' command previously?  This is why we ask you to give the
exact sequence of characters you typed since starting to use Emacs.

   You should not even say "visit a file" instead of `C-x C-f' unless
you *know* that it makes no difference which visiting command is used.
Similarly, rather than saying "if I have three characters on the line,"
say "after I type `RET A B C RET C-p'," if that is the way you entered
the text.

automatically generated by info2www