From 69351c59b6d95412928b92a6556c574cd6c0c4e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maxime=20=E2=80=9Cpep=E2=80=9D=20Buquet?= Date: Fri, 23 Nov 2018 11:31:58 +0000 Subject: [PATCH] bug-reports: small improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Maxime “pep” Buquet --- .../posts/how-to-write-a-good-bug-report.md | 93 ++++++++----------- 1 file changed, 41 insertions(+), 52 deletions(-) diff --git a/content/posts/how-to-write-a-good-bug-report.md b/content/posts/how-to-write-a-good-bug-report.md index 7bff8a7..92e9827 100644 --- a/content/posts/how-to-write-a-good-bug-report.md +++ b/content/posts/how-to-write-a-good-bug-report.md @@ -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