{(sk:page-preamble "Reporting a bug in Yenta" "icon-help" "Help")}

# Checklist for bug reports

The best way to send a bug report is to mail it electronically to the Yenta maintainers at bug-yenta@media.mit.edu. (If you want to suggest a change or an improvement, use the same address.)

We do not promise to fix the bug; but if the bug is serious, or ugly, or easy to fix, chances are we will want to.

To enable maintainers to investigate a bug, your report should include all these things:

- The version number of Yenta. Without this, we won't know whether there is any point in looking for the bug in the current version of Yenta. This Yenta is {(ui:yenta-version)}.

- The type of machine you are using, and the operating system name and version number. On this machine, this is "{(ui:yenta-uname)}".

- A complete list of any modifications you have made to the Yenta source. (We may not have time to investigate the bug unless it happens in an unmodified Yenta. But if you've made modifications and you don't tell us, you are sending us on a wild goose chase.)

  Be precise about these changes. A description in English is not enough--send a context diff for them.

  Adding files of your own, or porting to another machine, is a modification of the source.

- The precise commands we need to type to reproduce the bug.

- A description of what behavior you observe that you believe is incorrect. For example, "The Yenta exits when I didn't ask it to," or, "The resulting text is as follows, which I think is wrong."

  Of course, if the bug is that Yenta gets a fatal signal, then one can't miss it. But if the bug is incorrect text, the maintainer might fail to notice what is wrong. Why leave it to chance?

  Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as, your copy of the source is out of sync, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and the copy here might not. If you said to expect a crash, then when Yenta here fails to crash, we would know that the bug was not happening. If you don't say to expect a crash, then we would not know whether the bug was happening--we would not be able to draw any conclusion from our observations.

- If the manifestation of the bug is an Yenta error message, it is important to report the precise text of the error message.

- If you wish to mention something in the Yenta source, show the line of code with a few lines of context. Don't just give a line number.

  The line numbers in the development sources don't match those in your sources. It would take extra work for the maintainers to determine what code is in your version at a given line number, and we could not be certain.

- Additional information from a C debugger such as GDB might enable someone to find a problem on a machine which he does not have available. If you don't know how to use GDB, please read the GDB manual--it is not very long, and using GDB is easy. You can find the GDB distribution, including the GDB manual in online form, in most of the same places you can find the Yenta distribution.

  However, you need to think when you collect the additional information if you want it to show what causes the bug.

  For example, many people send just a backtrace, but that is not very useful by itself. A simple backtrace with arguments often conveys little about what is happening inside Yenta, because most of the arguments listed in the backtrace are pointers to Scheme objects. The numeric values of these pointers have no significance whatever; all that matters is the contents of the objects they point to (and most of the contents are themselves pointers).

  To provide useful information, you need to show the values of Scheme objects in Scheme notation. Do this for each variable which is a Lisp object, in several stack frames near the bottom of the stack. You need to run a "devo" version of Yenta for this to be possible; this requires wobbling a new Yenta from sources, and is not yet documented here.

- If the symptom of the bug is that Yenta fails to respond, don't assume Yenta is "hung"--it may instead be in an infinite loop. To find out which, make the problem happen under GDB and stop Yenta once it is not responding. (You can stop Yenta by typing `C-c' at the GDB job.) Then try stepping with `step'. If Yenta is hung, the `step' command won't return. If it is looping, `step' will return.

  If this shows Yenta is hung in a system call, stop it again and examine the arguments of the call. In your bug report, state exactly where in the source the system call is, and what the arguments are.

  If Yenta is in an infinite loop, please determine where the loop starts and ends. The easiest way to do this is to use the GDB command `finish'. Each time you use it, Yenta resumes execution until it exits one stack frame. Keep typing `finish' until it doesn't return--that means the infinite loop is in the stack frame which you just tried to finish.

  Stop Yenta again, and use `finish' repeatedly again until you get back to that frame. Then use `next' to step through that frame. By stepping, you will see where the loop starts and ends. Also please examine the data being used in the loop and try to determine why the loop does not exit when it should. Include all of this information in your bug report.

Here are some things that are not necessary in a bug report:

- A description of the envelope of the bug--this is not necessary for a reproducible bug.

  Often people who encounter a bug spend a lot of time investigating which changes to their commands will make the bug go away and which changes will not affect it.

  This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. You might as well save time by not searching for additional examples.

  Of course, if you can find a simpler example to report instead of the original one, that is a convenience. Errors in the output will be easier to spot, running under the debugger will take less time, etc.

  However, simplification is not vital; if you can't do this or don't have time to try, please report the bug with your original test case.

- A system call trace of Yenta execution.

  System call traces are very useful for certain special kinds of debugging, but in most cases they give little useful information. It is therefore strange that many people seem to think that the way to report information about a crash is to send a system call trace.

  In most programs, a backtrace is normally far, far more informative than a system call trace. Even in Yenta, a simple backtrace is generally more informative, though to give full information you should supplement the backtrace by displaying variable values and printing them as Lisp objects with `pr' (see above).

- A patch for the bug.

  A patch for the bug is useful if it is a good one. But don't omit the other information that a bug report needs, such as the test case, on the assumption that a patch is sufficient. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all. And if we can't understand what bug you are trying to fix, or why your patch should be an improvement, we mustn't install it. *Note Sending Patches::, for guidelines on how to make it easy for us to understand and install your patches.

- A guess about what the bug is or what it depends on.

  Such guesses are usually wrong. Even experts can't guess right about such things without first using the debugger to find the facts.

[Bug reporting in general | Sending patches for Yenta]

{(sk:page-postamble)}