GMU:Tutorials/Documentation/Bug Report How-To

""How to report a bug""

Introduction

On this Wiki-page I'll try to explain how you can write a good bug report. The aim of a bug report is to enable the programmer to see the program failing in front of them. You should give them careful and detailed instructions on how to make it fail. If they can reproduce the error, they will try to get as much information until they know the cause. If they can’t reproduce the error, you need to get that information for them.

State the facts…

In a bug report you should try to state clear facts what was happening to you when you used the program. Example: I was using the program to do this but this happened. If you have some speculations what might have happened you can include that but if you aren't sure about it just leave it out, it may cause more confusion than necessary.

Be Nice…

When you're writing the report you should write it in a friendly and polite form, it wont help if you insult them or anything in that direction. They may have programmed/developed it but they don't want it too fail when you're using it.

You cant just write “It doesn't work”…

Like i said above they don't want you to fail while using the program, since they haven't noticed the potential bug the program was running fine for them in their setup. So that in mind give them detailed information on how your setup is like cause its most likely different from the one they have. More clear information is always better then less. On What System are you running the Software What are the specs of your PC What Version/distribution of the Program/Software do you have

Asking for general help…

If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better.

Show it…

The best way to report the bug is to show it to the programmer since for example Mr. Hasler cant be here in Person every time you need to figure out another effective way to show them. They need to see how you start the PC, run the Software, see how you interact with it and how the Software responses. This step is very important so that they can try to reproduce the bug by themselves in order to fix it.

There are several possibilities: You can make a screen video of you reproducing the bug You can make screen shots and write information into them Write a detailed description of every click you made since you started the PC You could ask them to make a Skype or Teamviewer session with you to share your screen live 5. If you weren't precise enough do it over again as they wish, or try some variations to get

   to the same point were you actually wanted to be.

6. If its a graphical problem you're confronted with tell them exactly in wich order you

   pressed the buttons, if its a problem writing commands they need to know exactly what 
   commands you typed and what the computer outputted as response.

7. If you're loading the data from a specific file you created send them over to them. 8. If you're using the program to talk to another via Network Computer you also need to

   send them the specs of the other on too

Works for them but not for you…

If the programmer recreated your commands/inputs/actions/… and it works for them you may haven't given them enough information. Maybe the error doesn't appear on every Computer. Or you have got it wrong what the program is should do and is able too, so it maybe that you got it right but for your opinion its turning out wrong. 1. Provide the information of what your intention was by using the program. 2. Tell them what exactly happened 3. Tell them what you thought it should happen 4. Tell them exactly what Error message you saw 5. Are there unexplainable delays and when At this point the programmer still wants to reproduce your failure, they need to know what and where it has gone wrong. Write the errors down message and number are equally important, even if the computer cant give you out the information in words theres still important information in numbers or signs he's outputting.

And then i tried this to solve the Problem…

You probably have done some things after the bug showed up too you to fix it yourself, these action may have made things worse or changed something the programmer cant easily reproduce. Try to remember what you did afterwards and also give detailed information about that. If you're not sure what you're doing, don't do anything after the bug shows up you will make it worse! When something goes wrong, immediately stop doing anything. Don't touch any buttons at all. Just look at the screen and try to write down everything that isn't ordinary. The only things you can do by yourself is closing the program or rebooting the computer. Even if you're good at programming don't try to do things you don't know anything about, you aren't the person who has written the code so you can never be a hundred percent sure of anything what the company actually there. You describe the symptoms, don't assume a diagnosis it will only lead to general confusion. Even if you think the commands/changes etc. the programmer provides you with will not work cause you know it better, still try it there will be some reason he wants you to try that.

Sometimes it works…

If you're confronted with a bug that just occurs from time to time try to search for a pattern in it. Where you using an extra large file Did some other program access the file at the same time 3. Are you running any other programs you weren't running the last time 4. Do you use another display or beamer then before 5. Maybe you're just stressed cause of a deadline and weren't using the software carefully

     enough.

6. What version of the program you are using with wich version of your operating system

     Try different setups several times and write down how many times the bug occurred and     
      what differs to the times it was working.

Be specific no matter you're writing in english or german…

Don't just tell them i loaded that file into it, tell them how you loaded it by pressing keys, typing a command line or using graphical buttons. This can matter too. Write more than they actually need to know they're willing to ignore the information that isn't needed over getting to less information. If you write them to less information they need to come/mail back to you and ask you those things and the process will therefore take longer as giving them a good specific description in the first place. Dont use “it”: I used it then it opened a file and then it crashed. What did crash here, the opening of the file or the whole program. You also need to be careful while using pronouns, the programmer cant see into your setup unless he's standing right behind you. Read what you've written before you send it off to the programmer, go through your own steps and recreate the situation while using you're instructions as a guideline. Thats the best way to assume that the programmer will get to the same situation as you did.

Asking for general help…

If you are just asking for help and don't want to report a bug, you should tell the programmer where you already looked for information. They may can use this information to make they're own documentation better.

Summary

1. Let the programmer see what you've seen 2. If they cant see it failing themselves describe what went wrong 3. Describe everything in Detail 4. Tell them what you saw and what you were expecting to see 5. Write down the Error messages 6. When something unexpected happens leave the Situation like that until you're calm 7. Describe the symptoms don't make a diagnosis 8. Provide the programmer with any extra information he needs 9. Tell them you're version numbers 10. Be specific and write in clear language 11. Be sure you're description cant be misinterpreted