How to report Bugs effectively

Simon Tatham, compiled by: DASN

Introduction

People who have written software for the public have probably received very poor bug reports, such as:

• Say "not good" in the report;
• The contents of the report are meaningless;
• The user does not provide sufficient information in the report;
• Error messages are provided in the report;
• The problem reported is due to the user's negligence;
• The problems reported were due to errors in other procedures;
• The problem reported is a result of a network error;

This is why "technical support" is considered a terrible job because there are poor bug reports that need to be addressed. However, not all bug reports are annoying: I maintain free software in my spare time, and sometimes I get a very clear, helpful and "content" bug report.

Here I will try to explain how to write a good bug report. I really want everyone to read this short article before reporting a bug, and of course I would like the user to have read the article before reporting it to me .

Simply put, the purpose of reporting a bug is to let programmers see the bugs in the program. You can demonstrate it yourself, or you can give detailed steps that can lead to an error in the program. If the program goes wrong, the programmer collects additional information until it finds the cause of the error, and if the program does not go wrong, then they will ask you to continue to focus on the issue and gather relevant information.

In the bug report, try to figure out what the facts are (ex: "I'm on the computer" and "XX appears") What is speculation (for example: "I think the problem may be in ..."). If you want, you can omit the speculation, but don't omit the facts.

When you report a bug (since you've already done that), you'll want the bug to be fixed in a timely manner. So any aggressive or profane speech (or even abuse) against the programmer at this point is not going to help-because it could be a programmer's fault or your fault, maybe you have the right to be angry with them, but if you can provide more useful information (rather than words of anger), the bug will be corrected faster. In addition, please remember: if it is free software, the author has given us out of kindness, so if too many people rude to them, they may have to "put away" this kindness.

"Bad App"

Programmers are not retarded: If the program is not a good use, they can not know. They do not know that it must be because the program works well for them. So, either you've done something different with them, or your environment is different from them. They need information and report bugs to provide information. The more information is always the better.

Many programs, especially free software, will publish a "known bug list." If you find a bug that's already in the list, you don't have to report it, but if you think you have more information than you have in the list, then you need to contact the programmer anyway. The information you provide may make it easier for them to fix the bug.

Some of the guidelines are mentioned in this article, and none of them is a rule that must be adhered to. Different programmers will like different forms of bug reports. If the program comes with a set of guidelines for reporting bugs, be sure to read them. If it is inconsistent with the rules mentioned in this article, then please take it as the subject.

If you're not reporting a bug, but asking for help, you should explain where you've been looking for answers, (for example: I read section fourth and chapter fifth, but I can't find a solution.) This allows the programmer to understand where the user prefers to find the answer, making it easier for the programmer to use the Help document.

"Show me what I see."

One of the best ways to report a bug is to show it to the programmer. Let the programmer stand in front of the computer, run their programs, and point out the program errors. Let them see you start the computer, run the program, how to do it, and how the program reacts to your input.

They know the software they write about, knowing where it doesn't go wrong and where it's most likely to go wrong. They know instinctively what to pay attention to. Before the program really goes wrong, they may have noticed something is wrong, and these will give them clues. They observe every detail in the program test and select the information they think is useful.

These may not be enough. Perhaps they feel that they need more information, and will ask you to repeat the operation just now. They may need to communicate with you during this time to let the bug come back when they need it. They may change some of the actions to see if the error is a separate issue or a related one. If you're unlucky, they may need to sit down and take out a bunch of development tools and spend a few hours on a good look. But the most important thing is to let the programmer be near the computer when the program goes wrong. Once they see the problem, they usually find the cause and start trying to modify it.

"Tell me what to do."

Today is the network age, is the information exchange era. I can click on the mouse to send my program to a friend in Russia, of course, he can also use the same simple way to give me some advice. But if there's something wrong with my program, I can't be next to him. "Presentation" is a good idea, but it's often not.

If you have to report a bug, and the programmer is not around you, then you need to find a way to get the bug back in front of them. When they see the error in their own eyes, they are able to handle it.

Tell the programmer exactly what you have done. If it's a graphical interface program, tell them which button you pressed, in what order. If it's a command-line program, tell them exactly what command you typed. You should provide as much detail as possible with the responses of the Commands and programs you type.

Tell the programmer all the input methods you can think of, and if the program is going to read a file, you may need to send a copy of the file to them. If the program needs to communicate with another computer over the network, you may not be able to copy the computer, but at least say what type of computer you have and what software is installed (if you can).

"Where did it go wrong?" In my opinion, everything is fine. ”

If you give programmers a long list of inputs and instructions, they do not have errors after execution, because you do not give them enough information, maybe the error is not on every computer, your system may be different from their own in some places. Sometimes the program behaves differently than you might expect, which may be a misunderstanding, but you think the program is wrong and the programmer thinks it's right.

Also describe what happened. Describe exactly what you see. Tell them why you think what you see is wrong, and better tell them what you think you should see. If you just say, "The program went wrong," you're probably missing out on very important information.

If you see the error message, be sure to tell the programmer carefully and accurately, which is really important. In this case, the programmer simply corrects the error without looking for the error. They need to know what's wrong, and the error message that the system has reported just helps them. If you don't have a better way to remember these messages, write them down. It doesn't make sense to report only that the program has made a mistake, unless you put the error message in a newspaper.

In special cases, if you have an error message number, be sure to tell the programmer the number. Don't think that you don't see any meaning, it doesn't make sense. The error message number contains a variety of information that can be read by the programmer and is likely to contain important clues. The error message is numbered because it is often confusing to describe a computer error in a language. This is the best way to tell you where the error is.

In this case, the programmer's troubleshooting work can be very efficient. They don't know what's going on, they can't go to the spot, so they've been searching for valuable clues. The error message, the error message number, and some inexplicable delay are important clues, as important as the fingerprint of the case, and keep it.

If you use a UNIX system, the program may produce a kernel output (coredump). Kernel output is a particularly useful source of clues, don't throw them away. On the other hand, most programmers don't like to receive an email with a lot of kernel output, so it's a good idea to ask before sending an email. It is also important to note that the kernel output file records the complete program state, which means that any secret (perhaps the program is processing some private information or secret data) may be included in the kernel output file.

"After something went wrong, I did ..."

When an error or bug occurs, you may do a lot of things. But most people make things worse. A friend of mine mistakenly deleted all of her word files at school, and before looking for help she re-installed word and ran the defragmentation program, which is useless for recovering files because they mess up file chunks of the disk. I'm afraid there's no anti-removal software in the world that can recover her files. If she doesn't do anything, there may be a glimmer of hope.

This user is like a ferret (weasel, sable-type animal) forced to the corner: against the wall, facing the death of the advent of the fight, crazy attack. They think it's better to do something than to do nothing. However, these do not apply when dealing with computer software problems.

Do not be a ferret, be an antelope. When an antelope is confronted with unexpected situations or is frightened, it remains motionless in order not to attract any attention, while at the same time thinking about the best way to solve the problem (if the antelope has a technical support hotline, the line is busy at this time.) ）。 Then, once it finds the safest plan of action, it does it.

Stop Any action you are doing when the program is faulty. Do not press any health. Take a closer look at the screen, notice the abnormal places, remember it or write it down. Then carefully click on "OK" or "Cancel" to choose the safest one. Learn to develop a reflex--once the computer is out of the question, don't move. To get rid of this problem, shutting down the affected program or restarting the computer is bad, a good way to solve the problem is to let the problem arise again. Programmers like problems that can be reproduced, and happy programmers can fix bugs faster and more efficiently.

"I think the transition of the particles is related to the wrong polarization."

Not only non-professional users will write poor bug reports, I have seen some very poor bug reports from the programmer's hand, some are very good programmers.

Once I worked with another programmer, who was always looking for bugs in the code, and he often encountered a bug but couldn't solve it, so he asked me to help. "What's the problem?" "I asked. And his answer is always some comments about the bug. If his opinion is correct, it is a good thing indeed. That means he's done half the work, and we can do the other half of the work together. This is efficient and useful.

But in fact he is often wrong. This will make it take us half an hour to go back and forth in the correct code to look for errors, but in fact the problem is somewhere else. I'm sure he won't do this to the doctor. "Doctor, I got Hydroyoyodyne (it's a strange disease-translator), give me a prescription", people know not to say to a doctor. You describe the symptoms, which place is uncomfortable, where it hurts, a rash, a fever ... Let the doctor diagnose what disease you have and how to treat it. Otherwise, the doctor will send you as a suspect or mentally ill person, which seems to be nothing wrong.

It's the same with programmers. Even if your own "diagnosis" is sometimes really helpful, just say "symptoms". "Diagnosis" is not to say, but "symptoms" must be said. Similarly, it is useful to include a source code that makes changes to a bug in the bug report, but it does not replace the bug report itself.

If the programmer asks you for additional information, don't deal with it. There was a person who reported a bug to me, I told him to try a command, I knew the command was bad, but I wanted to see what error the program would return (this is a very important clue). But the man didn't even try, he said in his reply, "That must not be good," so it took me a while to persuade him to try the order.

It is helpful for the programmer to work with a lot of users. Even if your inference is wrong, programmers should thank you, at least you want to help them, make their work easier. But don't forget to report "Symptoms", otherwise it will only make things worse.

"What a strange, just not good, how is it now?" ”

The "Intermittent error" is really worrying for programmers. In contrast, the problem of making a series of simple operations that can cause errors to occur is simple. Programmers can repeat those operations in an easy-to-observe condition, observing every detail. Too many problems can not be solved in this case, for example: The program makes a mistake every week, or happens to be a mistake, or never make a mistake in front of the programmer (the programmer goes wrong when he leaves.) --translator). Of course, there is the deadline for the program, it must be wrong.

Most "intermittent errors" are not really "intermittent". Most of these errors are associated with certain places. Some of the errors can be caused by a memory leak, some of which may be the result of an inappropriate modification of an important file by another program, and some of it may occur in the first half hour of every one hours (I do experience this kind of thing).

Similarly, if you can reproduce the bug, and the programmer cannot, it is likely that their computer and your computer are different in some places, and this difference is causing the problem. I have written a program, its window can be curled up into a small ball in the upper left corner of the screen, it can only work on other computers in 800x600 resolution, but on my machine can work at 1024x768.

The programmer wants to know anything related to the problem you found. If possible, you can try it on another machine, try it several times, two times, three times, and see if the problem is not always happening. If the problem occurs after you have done a series of actions, it does not appear that you want it to appear, which can be an error caused by long running or working with large files. When the program crashes, you want to remember as much as you can about what you've done, and if you see any graphics, don't forget to mention it. Everything you provide is helpful. Even if it's a general description (for example, when the background has Emacs running, the program often goes wrong), which does not provide a direct clue to the problem, but may help the programmer reproduce the problem.

The most important thing is that the programmer wants to make sure that they are dealing with a real "intermittent error" or an error that occurs on a specific computer on another class. They want to know many details about your computer in order to understand how your machine differs from theirs. There are many details that depend on a particular program, but there is one thing you must provide-the version number. Version of the program, the version of the operating system, and the version of the program related to the problem.

"I loaded the disk into Windows ..."

It is clear that it is the most basic requirement in a bug report. If the programmer doesn't know what you mean, then you don't have to say the same thing. I have received bug reports from all over the world, many of them from non-English speaking countries, they usually apologize for their poor English. In general, the bug reports sent by these users are usually clear and useful. Almost all of the bug reports that are not clear are from native English speakers who always assume that as long as they speak casually, the programmer will understand.

precise . If there are two ways to do the same thing, please indicate which one you are using. For example: "I chose to ' load '", which may mean "I clicked on ' with the mouse '" or "I pressed ' alt+l '" to make it clear which method you used, and sometimes it's related.

detailed . More information than less! If you say a lot, programmers can omit a part, but if you say too little, they have to go back and ask you some questions. One time I got a bug report. Only one sentence, every time I asked him more things, he always reply is a sentence, so I spent a few weeks to get useful information.

use pronouns with caution . Words such as "it", "form" are not used when they are not clearly defined. To see this sentence: "I ran the Fooapp, it pops up a warning window, I try to turn it off, it crashes." "The expression is not clear, which window did the user turn off?" Is it a warning window or an entire Fooapp program? You can say, "I'm running the Fooapp program when I pop up a warning window, I try to close the warning window, Fooapp crashes." "It's a bit verbose, but it's clear it's not easy to misunderstand.

Check . Re-read the bug report you wrote, do you think it is clear? If you list a series of actions that can cause a program to go wrong, do it again and see if you missed a step.

Summary:

The primary purpose of the bug report is to have the programmer see the error with their own eyes. If you can't show them in person, give them detailed steps to make the program go wrong.

If the primary purpose is not achieved, the programmer cannot see the program error. This requires a second purpose of the bug report to describe where the program is going wrong. Describe everything in detail: what you see, what you want to see, write down the error message, especially the "error message number."

When your computer does something you can't imagine, don't move ! Don't do anything until you calm down. Don't do things that you don't think are safe.

Try to diagnose the cause of your program's error (if you think you can). Even if you make a "diagnosis," You should still report "symptoms."

Please prepare additional information if required by the programmer. If they don't need it, they won't ask you to. They don't deliberately embarrass themselves. You must have the version number of the program on hand, it is probably a necessity.

Make it clear that your meaning cannot be misinterpreted.

In general, the most important thing is to be precise . Programmers like precision.

How to report Bugs effectively