60.2 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 displays ‘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.