How to report bugs effectively

preface

As an ambitious and cultured programmer, besides being able to solve bugs, you also need to know how to report bugs effectively. The main content of this article is from an English blog, I translated and did some processing, friends who are good at English can also directly read the original.

An overview of the

Most people who have written open source software have received at least one bad bug report, for example

Just say the software doesn’t work
The content of the report makes no sense
Not enough information was provided
Wrong information is given
The problem arose from the user’s fault
The problem arose from a bug in another program
The problem arose from a network error

That’s why “tech support” is considered such a horrible job. However, not all bug reports are unpleasant. I’ve been maintaining open source software when I’m not making money, and sometimes I get very clear, helpful, and informative bug reports.

In this article, I’ll try to explain how to write a good bug report. I would very much like everyone to read this article before reporting a bug to others. Of course, I hope others have read this article before they mention bugs to me.

Simply put, the purpose of bug reporting is to show the programmer what is wrong with the program. You can demonstrate it yourself, or you can give detailed, specific instructions that will “reproduce the bug.” If the program does go wrong, the programmer will try to gather additional information until the cause of the error is found. If the program doesn’t go wrong, they may ask you to continue to collect more information for them.

In bug reports, sort out facts (” I have this problem on my computer “) and guesses (” I think this error should be… “). ), omit guesses if you like, but never omit facts.

When you report a bug, you expect it to be fixed. So bad language (or even abuse) directed at programmers is meaningless. The bug may be their fault, it may be your fault, you may have every right to be mad at them, but it can be fixed faster if you give them more useful information. And remember: if the software is free, the authors are offering it out of the goodness of their hearts, and they may have to take it back if too many people are rude to them.

First, the program is not easy to use

Programmers aren’t retarded, and they can’t fail to notice if the program isn’t working at all. If they don’t realize it, it must be because the program helps them. So maybe it’s because you don’t operate like them, or your environment isn’t like them. They need more information, and providing that information is the main purpose of bug reporting. More information is always better.

Many programs, especially open source programs, provide a “list of known bugs.” If you find a bug in the list, you need to read it. There’s no need to report the bug again, but if you think you know more than the list, Make sure you contact the programmers, they’ll be more likely to fix the bugs if you give them information they don’t already have.

This article is all about guidelines, not that they are necessarily strictly adhered to. Different programmers prefer different ways of reporting bugs. If you come with your own bug reporting guidelines, read them. If the guidelines in the program contradict the guidelines in this article, please follow the guidelines included with the program!

If you do not report a bug, but want to ask for help, you should say where to find the answer to the question: have you ever (for example, “I look at the fourth chapter and the fifth chapter in the second quarter, but can’t find the method to solve the problem”), this would allow the programmer to see people expect to find the answer, then they can make the document more easy to use.

Show me

One of the best ways to report a bug is to show it to the programmer. Have them stand in front of your computer, run their program, and demonstrate what went wrong. Show them how you start the machine, run the software, operate the software, and how the program reacts to your input.

They know what parts of the software they write are secure and what can go wrong. They know what to look out for. They might have sensed something was wrong before the program actually went wrong, which would give them a clue. They were able to watch everything the computer did during the test run and pick out the information they thought was useful.

That may not be enough. Maybe they feel they need more information and ask you to do it again. They may be able to communicate with you during this time so that they can reproduce the bug if they need to. They may try to change some of the actions to see if the problem is an individual problem or a class of problems. If you’re unlucky, they’ll sit down for a couple of hours with a whole set of development tools and work on it. But the most important thing is to have the programmer at the computer when something goes wrong. Once they see problems happening, they can usually figure out what the problems are and start trying to fix them.

Three, tell me what to do

This is the age of the Internet, this is the age of information exchange, this is the age when we can click a button and send software to our Russian friends, and they can easily evaluate it. But if he finds out there’s a problem with my software, I can’t be around him. “Demo” is a great way to do this, but many times it doesn’t work.

If you have to report the bug, but the programmers aren’t there, then you need to recreate the problem so that when they see it happen, they can deal with it.

So, you have to tell them what you did. If it’s a graphical program, you need to tell them what buttons you clicked and in what order you clicked them. If it’s a command line program, tell them exactly what you typed. In addition, you should provide as much detail as possible about the commands you enter and the responses the computer outputs.

Give the programmer every input you can think of. If the program needs to read a file, you may need to send them a copy of the file. If the program needs to network with another computer, you may not be able to send them a copy of the computer, but you should at least tell them what model the computer is and what software is installed.

Four, I here very normal ah, where went wrong?

If you give programmers a long list of inputs and actions, and then they run their own copy of the program and don’t find the problem, chances are you didn’t provide enough information. This error may not occur on every computer, and your computer system may differ from theirs in some way. It is also possible that you misunderstand how the program should display correctly. For example, you may see the same display and you think it is wrong, but the programmer thinks it is correct.

So also describe what happened, tell them what you saw and why you think what you saw was wrong. It’s best to tell them what you want to see happen. If you just say, “There’s a bug in the program,” you might be missing very important information.

If you see an error message, it is important to tell the programmer carefully and accurately. In this case, the programmer only needs to fix the bug, not find it. They need to know what went wrong, and the computer displays error messages to help them. If you don’t have an easier way to remember them, write them down. There is no point in reporting “an error occurred in the program.” You should report the error message as well.

In particular, when error messages contain numbers, be sure to tell the programmer those numbers. You may not see what these numbers mean, but that doesn’t mean they don’t mean anything. Numbers contain a lot of information that programmers can read, and may contain important clues. Using numbers to represent error messages is the best way to tell you what went wrong because it’s hard for a computer to describe what went wrong in words.

In this case, the programmer can do the troubleshooting work efficiently. They don’t know what’s going on, and they can’t see what’s going on up close, so they’ll look for clues as much as they can. Incorrect information, inexplicable string numbers, and even unexplained delays are important, so save them.

If you are using Unix systems, the program may produce a kernel output. Kernel output is an important source of clues, so don’t throw them away. On the other hand, most programmers don’t like to receive large kernel files via email, so it’s best to ask before sending them an email. It is also important to note that the kernel output file records the complete running state of the program: that is, any “secrets” (whether the program is working with private information or is working with secret data) can be contained in the kernel file.

Five, after the problem, I did…

You might do these things when errors or bugs occur. But most make the problem worse. I have a friend who mistakenly deleted all her Word documents at school. She tried to reinstall Word before seeking professional help. Then she tried running Defrag. These operations do nothing to recover her files, and they disrupt the disk’s file blocks, so there’s no anti-delete software in the world that can recover her files, and there’s a glimmer of hope if she doesn’t.

The user behaves like a weasel in a corner, with his back against the wall, facing death, mad at him because he thinks it’s better to do something than nothing, but that doesn’t suit the computer problem.

Don’t be a weasel, be like a gazelle. When antelopes are faced with unexpected situations or are frightened, they freeze, remain absolutely still and try not to attract any attention, then stop to think and plan their best response. When they find the safest solution, they do it.

When something goes wrong, stop doing anything. Don’t press any buttons, look at the screen carefully, then observe the abnormal things, remember and note. When it seems safe, you might want to start carefully clicking OK or Cancel. Try to get into the habit of “when a computer goes wrong, don’t do anything about it.”

If you want to fix the problem, closing the program or restarting the computer is not a good solution. The best solution is to re-create the problem. Programmers love problems that can be reproduced, and happy source code fixes bugs faster and more efficiently.

It is important to describe the symptoms

It’s not just non-programmers who write bad bug reports. I’ve also seen a lot of really bad bug reports from programmers, some of them really good ones.

I used to work with another programmer who was always looking for bugs in his code, often finding bugs that he couldn’t fix himself and asking me to fix them. “What’s the problem? I asked. His response, however, was always to give his opinion on the bugs.

If his opinion is correct, that is indeed a good thing. It means he’s done half the work, and we can do the other half together, which is very efficient and useful.

But more often than not, he was wrong. It takes a lot of time to find what went wrong, but we often end up spending half an hour looking for the wrong thing in the right code when the problem is somewhere else. I’m sure he wouldn’t dare do that to a doctor. “Doctor, I’ve got a strange disease. Give me a prescription.” People know not to say that to their doctors. We should describe the discomfort and pain, and then let the doctor decide what the problem is and how to treat it, otherwise the doctor will think you are a “psychopath.”

Programmers, too, can be helpful by offering their own judgment, but it’s best to name the symptoms. Judgment is optional, but “symptoms” must be said. Again, attaching a copy of the modified source code to a bug report is a good addition, but not a substitute for describing “symptoms.”

If a programmer asks you for more information, don’t respond. I once had a guy report a bug to me, and I asked him to type a command that I knew didn’t work, but I wanted to see what error the program would return (an important clue), but he didn’t try. He just emailed me and said, “It didn’t work.” Then I spent a lot of time trying to convince him to try the order once.

It’s nice to use your talents to help programmers. Even if your reasoning is wrong, programmers should be grateful that you at least want to help them make their lives easier. However, don’t forget to report the “symptoms,” which will only make things worse.

Seven, is really strange, just there are problems, now it is good

“Indirect errors” are a real source of frustration for programmers. The problem of doing a series of simple operations and then producing errors is easy to solve. The programmer can repeat those operations in a situation that is easy to observe, and then see what happens. But many problems cannot be solved in this situation. For example: make a mistake once a week, make a mistake once in a while, or never make a mistake in front of a programmer, but often come up close to a deadline.

Most “intermittent failures” are not really “intermittent”. Most of them are connected to some place. Some were caused by a machine running out of memory, some by another program modifying important files in the wrong place, and some occurred in the first half hour of each hour (I did experience these problems).

Also, if you can reproduce errors but the programmer can’t, your computer and theirs may be different in some way, and that difference is what causes the problem. I once wrote a program whose window would shrink into a small ball floating in the upper left corner of the screen. It worked at 800 × 600 resolution on other machines, but on my computer it worked at 1024 × 768 resolution.

Programmers want to know everything about the problem you find. If you can, try it once, twice, or even three times on another machine to see how often it makes mistakes. If the problem arises after you’ve done a series of rigorous tasks that you can’t demonstrate as well as you’d like, it’s probably due to long runs or processing large files. If something goes wrong, try to remember what you did before and remind yourself if you see a pattern. All the information you have provided is helpful. Even if it is only “probabilistic” (such as the fact that Emacs tends to crash more frequently when it is running), this may not provide a direct clue to the cause of the problem, but it helps the programmer reproduce it.

Most importantly, programmers will determine whether they are dealing with true intermittent failures or machine-specific failures. They will want to know a lot of details about your computer in order to figure out the difference between your computer and theirs. Many of these details depend on the specific program, but one thing you should be prepared for is the “version number” of the program itself, the version number of the operating system, and any other programs that might be relevant to the problem.

I loaded the disk into Windows…

In bug reports, it is necessary to clearly describe the problem. If the programmer can’t understand what you’re saying, you might as well not have said it.

I get bug reports from all over the world. Many are from non-English speaking countries. They usually apologize for their poor English. But overall, their bug reports are very clear and useful. Almost all of the vaguest reports come from native English speakers who think they can get the programmer to understand their problem by just saying something.

Be clear: if you can use two different methods, please state which one you use. For example, if I choose to load it might mean “I hit load” or “I hit Alt + L”, it’s important to be clear about exactly what you did.
Be more specific: The more information the better. If you say too much, the programmer can ignore some of it, but if you say too little, the programmer will have to come back to you with more questions. I once received a “one sentence bug report”. Every time I asked him more, he simply replied with one sentence. And it took me weeks to get enough information.
Pronoun Caution: Don’t use words like “it” or “the window” when their meaning is unclear. For example, “I opened FooApp and it brought up an alert window, I tried to close it and it crashed”. It’s not clear exactly what the user is trying to turn off. Do they try to close the warning window, or the entire FooApp? You can say something like, “I started FooApp, it brought up an alert, I tried to close the alert, and FooApp crashed.” This is longer and wordy, but clear and less likely to lead to misunderstandings.
Double check: Please read your bug report carefully. Do you think it’s clear? If you have a list of actions that might fail, try tracking them yourself to see if you missed any steps.

conclusion

The most important thing about bug reporting is to let programmers see the bug in front of them. If you can’t make the bug go wrong in front of them, give them details so they can reproduce the bug.
If the most important goal is not successful and the programmer cannot see the error for himself, the second goal of bug reporting is to describe what went wrong. Describe all the details, say all the information you see, and say what you expect to see. Note down the error message, especially the “wrong number”.
If something unexpected happens to your computer, don’t move. Please do not do anything that you think might be dangerous until you have calmed down.
If you think you can, try to diagnose the error yourself, and if you do, you should also report the “symptoms” to the programmer.
Provide additional information if the programmer needs it, they don’t ask for it if they don’t need it, they don’t make it hard on themselves. If you have a version number, it’s probably necessary.
Please state clearly what the problem is and make sure they are not misunderstood.
In general, be as “precise” as possible, because programmers love precision.