pep/blog.bouah.net
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

bug-reports: small improvements

Browse source 
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
This commit is contained in:
Maxime “pep” Buquet 2018-11-23 11:31:58 +00:00
parent 430061698b
commit 69351c59b6
1 changed files with 41 additions and 52 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

93
content/posts/how-to-write-a-good-bug-report.md
View file

@ -4,13 +4,14 @@ date: 2018-11-13T03:15:00+00:00
tags: [sysadmin, projects, collabora] tags: [sysadmin, projects, collabora]
--- ---
As some of you may know, I work at [Collabora], as a Systems Administrator, As some of you may know, I work at [Collabora] as a Systems Administrator, and
and part of my job is to provide support to technical and non-technical part of my job is to provide support to technical and non-technical
"customers" (mostly colleagues, sometimes Collabora's customers). "customers" (mostly colleagues, sometimes Collabora's customers).
We have recently been changing our ticketing system, and in the process of 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 doing so I found myself explaining again how to write tickets. This is mostly
I might do it here, as it might also be useful to others. aimed at non-technical people that I support as part of my job, but I thought
I might do it here as it might also be useful to others.
I also regularly contribute to free software projects, and I encounter lots of I also regularly contribute to free software projects, and I encounter lots of
what I consider bad bugs reports, i.e., incomplete, reporting the wrong what I consider bad bugs reports, i.e., incomplete, reporting the wrong
@ -21,16 +22,10 @@ There is already a [plethora] [bug-report1] [of] [bug-report2] [resources]
subject in depth, but I don't think it hurts talking about it more. And also subject in depth, but I don't think it hurts talking about it more. And also
for some reason I can't shake this off my head at 3 in the morning. for some reason I can't shake this off my head at 3 in the morning.
This is mostly aimed at non-technical people that I support as part of my job, This is _not_ a comprehensive list and there are many things you can do to
but it might be helpful for others as well. Comments welcome. help sysadmins or project maintainers. It's important to find a good balance
between what you can do and what the person on the other end will be able to
This is also applicable if you want to report bugs to any other projects in do with the information.
the future, and will likely 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 can do and what the person on the other end will be
able to do with the information.
[Collabora]: https://collabora.com [Collabora]: https://collabora.com
@ -44,14 +39,14 @@ able to do with the information.
Why would you need to write a bug report/file a ticket in the first place? 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. What first comes to mind is that sysadmins might not know you have issues, and
And it would probably be beneficial for you, and possibly others, that you it would probably be beneficial for you, and possibly others, that you tell
tell them. them.
A ticket is also helpful to be able to track the progress. This will also A ticket is also helpful to be able to track progress of a task. This will
help other users encountering the same issue and allow them to fix it also help other users encountering the same issue and allow them to fix it
themselves, or allow you to refer to it in a follow-up ticket, ("You know, themselves, or allow you to refer to it in a follow-up conversation, ("You
_that_ bug I talked to you about six months ago.") know, _that_ bug I talked to you about six months ago.")
It is also helpful to track the resolution of an issue, ("What happened to my 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 issue?"). Some issues will get fixed and closed, some will not, some might be
@ -100,37 +95,37 @@ discarding them entirely.
I have an issue, now what? I have an issue, now what?
Make sure this is _only one_ issue. Do not mix different things together. It Try to ensure this is _only one_ issue. Do not mix different things together,
makes it easier to isolate and track. People on the other side will be more it makes it easier to isolate and track. People on the other side will be
capable at helping you with precise indications. It happens that you do not more capable at helping you with precise indications. It happens that you do
know, and in this case they might split the task for you. not know, and in this case they might guide you and/or split the task for you.
### Existing tools ### Existing tools
Some applications already include automatic bug/crash reporting. For example 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 in [Firefox][crash-report] if you type "about:crashes" in the URL bar, you
all crash reports that have been generated for you and sent to Mozilla servers will get a list of all crash reports that have been generated for you and sent
if you so chose at the time. See more details about this to Mozilla servers if you so chose at the time. These reports include data
[here](https://support.mozilla.org/en-US/kb/mozillacrashreporter). useful for developers to find the cause of the crash.
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 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. this case you can link one or multiple related crash reports in it.
[crash-report]: https://support.mozilla.org/en-US/kb/mozillacrashreporter
### Reproducibility ### Reproducibility
This part is about writing down the steps that lead you to the issue. These 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 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 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 to reproduce they will only be able to guess, or most likely unable to help
all. you at all.
The steps can be as simple as: The steps can be as simple as:
- Open applicationA - Open applicationA
- Click on buttonB - Go to tabB
- Click on buttonC
If the issue appear when clicking the button, this is perfect. If the button 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. seems to be the cause but you are not entirely sure, please also say so.
@ -138,6 +133,10 @@ 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, Include any information about your system, what distribution you are using,
what software version. Some configuration information also helps. what software version. Some configuration information also helps.
You can usually get all this information in the help menus of applications.
![][gnome-version].
As sysadmin, what I will be looking after is patterns, to try and identify 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 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. if there is code to fix for it, or if it is a configuration or user mistake.
@ -156,30 +155,20 @@ If so [please] copy it.
Was there some UI element out of place? Or maybe the issue is hard to explain? Was there some UI element out of place? Or maybe the issue is hard to explain?
You could attach a screenshot. 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.
[please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/ [please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/
### Why is this a bug / What do you expect instead? ### Why is this a bug?
This is also a pretty important step. What makes you think this is a bug? What did you expect the application to do
instead? It might be obvious to some but not to others.
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, When reporting to a project, if there is no obvious solution for your issue,
maybe you can propose a few ideas to guide developers. you may want to propose a few ideas to guide developers.
## I have submitted the report ## I have submitted the report
Thanks a lot! I _really_ appreciate it. Thanks a lot! I _really_ appreciate it. But wait, don't leave! The adventure
has only just started.
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 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 from this article I would want it to be the following: _Please help me help