All you need to know about bug reporting
/Bugs are a fact of life in software. There will always be bugs, we just need to find a streamlined way of catching them, reporting them, fixing them and deploying a new version with at least that bug fixed. In this process of catching bugs and removing them from the software the role of bug reporting is vitally important. If not done right valuable time is lost in clarifying what the bugs was about and in the worst cases important bugs are either forgotten or deprioritized. This situation makes the software less usable and eventually if this situation continues the users stop using the software - which is effectively the death of a software. So today I want to go over one of the least exciting topics in software development yet one of the most important one - reporting bugs in a way that is effective, efficient and clear.
The bug report
The best bug reports are short with a step by step "how to recreate" section and an expected results section. It’s pretty easy to remember the rule for a good bug report. Every bug should have at least the following:
Steps to reproduce the bug.
What was the result?
What was the expected result?
By laying out the result and the expected result the bug report is clearly showing to the developer the gap. The developer can now use #1 to recreate the bug, look at the result and check why it’s not giving the expected result.
Here’s an annotated example of a great report from a really good post about how bug reports should be done.
Apart for the basic facts above, additional data such as screen grabs and links to the product page are always good to have. Something else that also matters is the context of the bug - if there was a special situation when it happens (ideally that should be part of the steps to reproduce, but sometimes it may be hard to put that in there). If your bug is related to a specific hardware device and you should attach your device ID, it helps the developers find the bug faster and fix it sooner.
Including as much detail as possible makes finding and fixing your bug faster, remember that when reporting the bug the state of the software may be completely different from the time when the bug is being re-created and fixed. Many times a bug that was reported cannot be recreated by the developer. The reason could be that a step was missed in the bug's description or the state of the software at that particular situation needs to be in certain way for the bug to recreated. I remember a particularly nasty bug that would only happen at the QA's machine but never on my dev machine. The reason was that the QA would always run the web app by clearing his cache which would create a situation very different from my one where a certain cookie was always set. So the bug was really about not managing the cookie's absence.
Sometimes there could be many bugs that you report without realizing it. For example if the application is doing something wrong in a situation where you expect it to do something different and you thought you had reported the only bug and then discover another one after some time, chances are that your first bug was actually two separated ones and not one big one. The QA needs to think through every bug to see how it happened.
As you can see, describing a bug is not as easy as it looks and chances are that if you report a bug like this: "I opened the app and clicked 'login' but I was on the 'welcome' screen and there was no way to go back", then it will be impossible for developers to fix that. And it will end up spending everyone's time.
The process after the report
After submitting your bug report in an issue tracker, it should first be picked up based on severity of the bug. If the bug is a show stopper, a bug that stops the software from working then it should be prioritized over all other bugs and if needed current development flow will need to be changed to fix the bug so that it hits the next release. If it happens not to be a show stopper but just an inconvenience, then it gets bumped down the list and is fixed over all other bugs that are also being worked on. The issue tracker should be available to the original reporter of the bug (maybe the QA person or even the user of the software) who can easily track it down and see the status of the fix.
Another important thing with a bug report is the history of the bug. Every bug should show when it was started, what happened during it’s fixing, the exchange in information that happened to clarify the bug and finally the fix and the confirmation of the fix. So a history of the workflow per bug is a must and every software development process should use an issue tracker that supports such history. The good news is most modern day issue tracker such as Jira, Github, fogbugz, etc. support this buy default. Even the simple trello board is good for this.
