7 KiB
| title | date | tags | |||
|---|---|---|---|---|---|
| How to write a good bug report | 2018-11-13T03:15:00+00:00 |
|
As some of you may know, I work at Collabora, as a Systems Administrator, and part of my job is to provide support to technical as well as non-technical "customers" (mostly colleagues, but also sometimes Collabora's customers).
We have recently been changing our ticketing system, and in the process of doing so, I found myself explaining again how to write tickets, so I thought I might do it here, as it might also be useful to others.
I am sure there is already a plethora of resources out there talking about this subject in depth, but it took me shorter to write than to look for anything on the subject. And also for some reason I can't shake this idea off my head at 3 in the morning.
This is mostly aimed at non-technical people that I support as part of my job, but it might be helpful for others as well. Comments welcome.
This will also likely be applicable if you want to report bugs to any other projects in the future. It might also apply to feature requests as well.
This is not a comprehensive list and there are many things you can do to help sysadmins or project maintainers. It's important to find a good balance between what you know or can do and what the person on the other end will be able to do with your help or for you.
Why bug reports?
Why would you need to write a bug report/file a ticket in the first place?
What first comes to mind is that sysadmins might not know you have issues. And it would probably be beneficial for you, and possibly others, that you tell them.
A ticket is also helpful to be able to track the progress. This might help future you encountering the same issue again be able to fix it yourself, or to refer to it later on.
It is also helpful to track the resolution of an issue, ("What happened to my issue?"). Some issues will get fixed and closed, some will not, some might be closed for reasons, without getting fixed.
Why write a good bug report?
You might tell yourself "I don't know anything about computers", and as true as it can be, this is not a requirement to write good bug reports. The error message, if available, or information about your system can easily be obtained and put into the report.
Others might not want to bother, or "don't have time" to write good bug reports. There are a few issue with this if you wish to have your ticket resolved.
Forgetting about the job for a second, in the context of a free software project for example, where people often volonteer, they might just not bother answering you in return if you don't do any effort.
For my use-case, as I am paid to provide support, the issue is that questions you don't answer in this first ticket will eventually need to asked some way or another. Every detail you can give is that much time gained avoiding back and forth for both parties.
Sysadmins might know about common issues or errors and ways to fix them, but we don't have magical powers (unfortunately?) and we need your help to understand the issue.
An unhelpful party is only making the process more painful for all parties involved.
What is a bug?
This is a trick question.
My helpful friend Wikpedia says, "an error, flaw, failure or fault in a computer program or system that causes it to produce an incorrect or unexpected result, or to behave in unintended ways."
I would try to answer it saying that a bug is everything that a piece of software was designed for, that it is not doing correctly.
This is all vague and subjective, and will sometimes be the cause of project maintainers not accepting your bugs as bugs, but as feature requests, or even discarding them entirely.
How
I have an issue, now what?
Existing tools
Some applications already include automatic bug/crash reporting. For example in Firefox if you type "about:crashes" in the URL bar, you will get a list of all crash reports that have been generated for you and sent to Mozilla servers if you so chose at the time. See more details about this here.
These reports include data useful for developers to find the cause of the crash, and will be stripped out of personal information as possible.
Often it is still good to have a bug report tracking a particular issue. In this case you can link one or multiple related crash reports in it.
Reproducibility
This part is about writing down the steps that lead you to the issue. These are unfortunately not always known, but it is one of the most critical piece of information in the life cycle of a bug request. If sysadmins don't manage to reproduce, they will likely only be able to guess, or unable to help you at all.
The steps can be as simple as:
- Open applicationA
- Click on buttonB
If the issue appear when clicking the button, this is perfect. If the button seems to be the cause but you are not entirely sure, please also say so.
Include any information about your system, what distribution you are using, what software version. Some configuration information also helps.
As sysadmin, what I will be looking after is patterns, to try and identify what part of the system and software is responsible, where the issue lies and if there is code to fix for it, or if it is a configuration or user mistake.
It often feels to me like playing detectives. The more patterns I observe, the more suspects I can cross off my list. It is rewarding to finally solve a complex case, but "boring" ones also help with mental health.
What happens?
Did anything happen at all?
Describe in details what you saw (not) happening. Was there an error message? If so please copy it.
Was there some UI element out of place? Or maybe the issue is hard to explain? You could attach a screenshot.
Application logs are also a gold mine, but they are often hidden to users, thus I do not really expect to see them and will often go get them myself if they exist.
Sometimes it is easier for me to get information directly from the system, to avoid you wasting time with things you do not know or I can do myself.
Why is this a bug / What do you expect instead?
This is also a pretty important step.
What makes you think this is a bug? Can you explain what you were expecting? It might be obvious to some but not to others.
When reporting to a project, if there is no obvious solution for your issue, maybe you can propose a few ideas to guide developers.
I have submitted the report
Thanks a lot! I really appreciate it.
But wait! Don't leave! The adventure has only just started.
If you managed to read until here, great! If there is one thing to remember from this article I would want it to be the following: Please help me help you.