0.2 Submitting bug reports  (Page 4/4)

Would you do that to a doctor? "Doctor, I need a prescription for Hydroyoyodyne." People know not to say that to a doctor: you describe the symptoms, the actual discomforts and aches and pains and rashes and fevers, and you let the doctor do the diagnosis of what the problem is and what to do about it. Otherwise the doctor dismisses you as a hypochondriac or crackpot, and quite rightly so. It's the same with programmers. Providing your own diagnosis might be helpful sometimes, but always state the symptoms. The diagnosis is an optional extra, and not an alternative to giving the symptoms. Equally, sending a modification to the code to fix the problem is a useful addition to a bug report but not an adequate substitute for one.

If you are asked for extra information, don't make it up! Don't skip any diagnostic steps you're asked to perform, because they will [hopefully] lead to a solution. Using your intelligence to help the programmer is fine. Even if your deductions are wrong, the developer should be grateful that you at least tried to make their life easier. But report the symptoms as well, or you may well make their life much more difficult instead.

"that's funny, it did it a moment ago"

Say "intermittent fault" to any developer, and watch their face fall. The easy problems are the ones where performing a simple sequence of actions will cause the failure to occur. They can then repeat those actions under closely observed test conditions and watch what happens in great detail. Sadly, too many problems simply don't work that way: there will be programs that fail once a week, or fail once in a blue moon, or never fail when you try them in front of the programmer but always fail when you have a deadline coming up.

Most intermittent faults are not truly intermittent. Most of them have some logic somewhere. Some might occur when the machine is running out of memory, some might occur when another program tries to modify a critical file at the wrong moment, and some might occur only in the first half of every hour!

If you can reproduce the bug but the programmer can't, it could very well be that their system and your system are different in some way and this difference is causing the problem. For example, a program whose window curled up into a little ball in the top left corner of the screen, and sat there and sulked. But it only did it on a user's 800x600 screen; it was fine on the developer's 1024x768 monitor.

The developers will want to know anything you can find out about the problem. Try it on another machine, perhaps. Try it twice or three times and see how often it fails. If it goes wrong when you're doing serious work but not when you're trying to demonstrate it, it might be long running times or large files that make it fall over. Try to remember as much detail as you can about what you were doing to it when it did fall over, and if you see any patterns, mention them. Anything you can provide has to be some help. Even if it's only probabilistic (such as "it tends to crash more often when Emacs is running"), it might not provide direct clues to the cause of the problem, but it might help the programmer reproduce it.

Most importantly, the programmer will want to be sure of whether they're dealing with a true intermittent fault or a machine-specific fault. They will want to know lots of details about your system, so they can work out how it differs from theirs. A lot of these details will depend on the particular tool, but one thing you should definitely be ready to provide is the version number. The version number of the program itself, and the version number of the operating system, and probably the version numbers of any other programs that are involved in the problem.

"so i loaded the disk on to my windows ..."

Writing clearly is essential in a bug report. If the programmer can't tell what you meant, you might as well not have said anything. Be specific. If you can do the same thing two different ways, state which one you used. "I selected Load" might mean "I clicked on Load" or "I pressed Alt-L". Say which you did. Sometimes it matters. Be tersely verbose - explain everything you did, but use bullet points if possible, rather than prose form. Give more information rather than less. If you say too much, the programmer can ignore some of it. If you say too little, they have to come back and ask more questions.

Be careful of pronouns. Don't use words like "it", or references like "the window", when it's unclear what they mean. Consider this: "I started FooApp. It put up a warning window. I tried to close it and it crashed." It isn't clear what the user tried to close. Did they try to close the warning window, or the whole of FooApp? It makes a difference. Instead, you could say "I started FooApp, which put up a warning window. I tried to close the warning window, and FooApp crashed." This is longer and more repetitive, but also clearer and less easy to misunderstand.

Read what you wrote. Read the report back to yourself, and see if you think it's clear. If you have listed a sequence of actions which should produce the failure, try following them yourself, to see if you missed a step.

Summary

The first aim of a bug report is to let the programmer see the failure with their own eyes. If you can't be with them to make it fail in front of them, give them detailed instructions so that they can make it fail for themselves. In case the first aim doesn't succeed, and they can't see it failing themselves, the second aim of a bug report is to describe what went wrong. Describe everything in detail. State what you saw, and also state what you expected to see. Write down all error messages, especially if they have numbers in them.

When your computer does something unexpected, freeze. Stop, Drop, and Roll . Do nothing until you're calm, and don't do anything that you think might be dangerous.

By all means try to diagnose the fault yourself if you think you can, but if you do, you should still report the symptoms as well.

Be ready to provide extra information if the asked for it. If it isn't needed, it wouldn't be asked for. The developers aren't being deliberately awkward. Have version numbers at your fingertips, because they will probably be needed.

Write clearly. Say what you mean, and make sure it can't be misinterpreted.

Above all, be precise. Programmers like precision.