{(sk:page-preamble "Reporting a bug in Yenta" "icon-help" "Help")}
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:
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.
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.
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.
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 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.
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.
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 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.
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)}