GNU Info

(emacs)Understanding Bug Reporting

---

Next: Checklist Prev: Bug Criteria Up: Bugs

---

Enter node , (file) or (file)node

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_.  Hypotheses and verbal descriptions are no substitute for the
detailed raw data.  Reporting the facts is straightforward, but many
people strain to posit explanations and report them instead of the
facts.  If the explanations are based on guesses about how Emacs is
implemented, they will be useless; meanwhile, lacking the facts, we will
have no real information about the bug.

   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
displayed `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.

   A bad way would be to assume that the problem is due to the size of
the file and say, "I visited a large file, and Emacs displayed `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 see any problem.  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 the Emacs session.

   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.

   So please don't guess any explanations when you report a bug.  If you
want to actually _debug_ the problem, and report explanations that are
more than guesses, that is useful--but please include the facts as well.