Why You Should Spend (More) Time Submitting a Bug Report

During the last few months, I have been working on the maintenance of LiveCode 6.7.x and LiveCode 7.0.x releases. This mainly involves fixing bugs. I have come across many different types of bug reports in terms of quality and clarity. In this post, I will describe how important is to provide a well-structured bug report as well as some tips on how to produce a high quality bug report.

In general, LiveCode users submit decent bug reports (thank you). However, some reports are vague and provide little information. Some others (thankfully very few) are complaints that “component X is not working,” rather than a bug report. There is no point in exploding at the programmer; it may, in fact, be their fault (it may not be), and I might have a right to be angry with them (or I may not), but the bug will get fixed faster if I help them by supplying all the information they need.

Therefore, the most important thing is to be specific. We need information; providing this information is the purpose of a bug report. More information is always better than less. Avoid general descriptions like “this does not work as expected” or “this does not work at all.” If this really didn’t work at all, we probably would have noticed, so it must be working on our end. So, either you are doing something differently or your environment is different from ours. For this reason, it is really important to attach a sample stack that exhibits the failure. Of course, I understand that someone may want to keep their stack private (as it may contain sensitive information). In that case, you can always email us with your confidential stack. Moreover, along with the attached stack, we need a detailed recipe of how to replicate the failure. Ideally, we like to see bullet points outlining the necessary steps followed by a description of both the expected and the observed result. Make sure that using the sample stack and following the recipe is enough for us to replicate the problem.

But what happens if the bug does not occur 100% of the time? Say you notice a random, intermittent failure. This is probably the worst kind of bug, since if we don’t have a concrete recipe on how to replicate the bug, it is highly likely that we will have difficulty finding and fixing the issue. However, most intermittent failures are not truly intermittent and have some logic somewhere. Also, if you can reproduce the bug and we cannot, it might be the case that our machines are different in some way and this difference is causing the problem. In that case, it would be really useful to discuss your problem with other community members in LiveCode forum. Recently, we received a bug about LiveCode 7.0 not being able to start up on Windows 8.1. We could not reproduce this behaviour, although the user was very helpful in providing as much information as he could in regards to his system. While we were investigating this bug, the solution came from the LiveCode forum. Another user noticed that activating the printer spooler on Windows fixes the start-up issue!

Before taking time to write a detailed bug report, make sure that this issue is not already reported. This is why the title (or summary) of the bug report has to be meaningful and descriptive; the bug summary is used as a reference to search for the bug in the bug inventory. If the bug is already reported, you can add any extra information that might help other developers in identifying the problem.
When the bug is related to the stack layout or appearance, for example a UI element appearing in the wrong position, it is really useful to provide a screenshot. After all, a picture is worth a thousand words.
If a crash has occurred, we recommend that you attach crash logs to a ticket as a file rather than paste it in as raw text. In this way, the crash log is far more readable and it makes it easier for us to extract any useful information.

At this point I have to say that some users provide bug reports of really high quality. Not only do they follow the previous guidelines, but they also mention what they think went wrong and suggest how to fix it. Sometimes they even provide a workaround, to help others tackle the problem until the bug is fixed. This is really important and promotes cooperation and participation, which are vital to an open source product like LiveCode.
So next time you are about to report a new bug, spend some more time. Remember that if your bug report is effective, chances are higher that it will get fixed soon.