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 60c09e3..5b02a3d 100644 --- a/content/posts/how-to-write-a-good-bug-report.md +++ b/content/posts/how-to-write-a-good-bug-report.md @@ -1,189 +1,189 @@ ---- -title: "Help me help you" -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 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 also regularly contribute to free software projects, and I encounter lots of -what I consider bad bugs reports, i.e., incomplete, reporting the wrong -things, too many things in the same bag, etc. - -There is already a [plethora] [bug-report1] [of] [bug-report2] [resources] -[bug-report3] [out] [bug-report4] [there] [bug-report5] talking about this -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. - -[Collabora]: https://collabora.com - -[bug-report1]: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html -[bug-report2]: https://wiki.documentfoundation.org/QA/BugReport -[bug-report3]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines -[bug-report4]: https://www.quora.com/How-do-I-write-bug-reports -[bug-report5]: https://duckduckgo.com/?q=write+bug+reports - -## 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](https://en.wikipedia.org/wiki/Software_bug), -"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? - -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. - -### 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. - -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. - -[please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/ - -### 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_. +--- +title: "Help me help you" +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 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 also regularly contribute to free software projects, and I encounter lots of +what I consider bad bugs reports, i.e., incomplete, reporting the wrong +things, too many things in the same bag, etc. + +There is already a [plethora] [bug-report1] [of] [bug-report2] [resources] +[bug-report3] [out] [bug-report4] [there] [bug-report5] talking about this +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. + +[Collabora]: https://collabora.com + +[bug-report1]: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html +[bug-report2]: https://wiki.documentfoundation.org/QA/BugReport +[bug-report3]: https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines +[bug-report4]: https://www.quora.com/How-do-I-write-bug-reports +[bug-report5]: https://duckduckgo.com/?q=write+bug+reports + +## 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](https://en.wikipedia.org/wiki/Software_bug), +"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? + +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. + +### 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. + +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. + +[please]: https://secure.phabricator.com/book/phabflavor/article/please_please_please/ + +### 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_.