bug-reports: small improvements
Signed-off-by: Maxime “pep” Buquet <pep@bouah.net>
This commit is contained in:
parent
430061698b
commit
69351c59b6
1 changed files with 41 additions and 52 deletions
|
|
@ -4,13 +4,14 @@ date: 2018-11-13T03:15:00+00:00
|
|||
tags: [sysadmin, projects, collabora]
|
||||
---
|
||||
|
||||
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 and non-technical
|
||||
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 and non-technical
|
||||
"customers" (mostly colleagues, 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.
|
||||
doing so I found myself explaining again how to write tickets. This is mostly
|
||||
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
|
||||
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
|
||||
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,
|
||||
but it might be helpful for others as well. Comments welcome.
|
||||
|
||||
This is also applicable if you want to report bugs to any other projects in
|
||||
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.
|
||||
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
|
||||
|
||||
|
|
@ -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?
|
||||
|
||||
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.
|
||||
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 will 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,
|
||||
_that_ bug I talked to you about six months ago.")
|
||||
A ticket is also helpful to be able to track progress of a task. This will
|
||||
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 conversation, ("You
|
||||
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
|
||||
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?
|
||||
|
||||
Make sure this is _only one_ issue. Do not mix different things together. It
|
||||
makes it easier to isolate and track. People on the other side will be more
|
||||
capable at helping you with precise indications. It happens that you do not
|
||||
know, and in this case they might split the task for you.
|
||||
Try to ensure this is _only one_ issue. Do not mix different things together,
|
||||
it makes it easier to isolate and track. People on the other side will be
|
||||
more capable at helping you with precise indications. It happens that you do
|
||||
not know, and in this case they might guide you and/or split the task for you.
|
||||
|
||||
### 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](https://support.mozilla.org/en-US/kb/mozillacrashreporter).
|
||||
|
||||
These reports include data useful for developers to find the cause of the
|
||||
crash, and will be stripped out of personal information as possible.
|
||||
Some applications already include automatic bug/crash reporting. For example
|
||||
in [Firefox][crash-report] 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. These reports include data
|
||||
useful for developers to find the cause of the crash.
|
||||
|
||||
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.
|
||||
|
||||
[crash-report]: https://support.mozilla.org/en-US/kb/mozillacrashreporter
|
||||
|
||||
### 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.
|
||||
to reproduce they will only be able to guess, or most likely unable to help
|
||||
you at all.
|
||||
|
||||
The steps can be as simple as:
|
||||
|
||||
- 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
|
||||
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,
|
||||
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
|
||||
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.
|
||||
|
|
@ -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?
|
||||
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/
|
||||
|
||||
### 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? Can you explain what you were expecting?
|
||||
It might be obvious to some but not to others.
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
Thanks a lot! I _really_ appreciate it.
|
||||
|
||||
But wait! Don't leave! The adventure has only just started.
|
||||
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue