52.3 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. If you want to actually debug the problem, and report explanations that are more than guesses, that is useful—but please include the raw facts as well.

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 bug report would need to provide all that information. You should not 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 might 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 we could guess that we should try visiting a file with a ‘ z’ in its name.

You should not even say “visit a file” instead of C-x C-f. 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.

If possible, try quickly to reproduce the bug by invoking Emacs with emacs -Q (so that Emacs starts with no initial customizations; see Initial Options), and repeating the steps that you took to trigger the bug. If you can reproduce the bug this way, that rules out bugs in your personal customizations. Then your bug report should begin by stating that you started Emacs with emacs -Q, followed by the exact sequence of steps for reproducing the bug. If possible, inform us of the exact contents of any file that is needed to reproduce the bug.

Some bugs are not reproducible from emacs -Q; some are not easily reproducible at all. In that case, you should report what you have—but, as before, please stick to the raw facts about what you did to trigger the bug the first time.

If you have multiple issues that you want to report, please make a separate bug report for each.