[Xposed Framework Modules] trjlive:
How To Provide Proper Bug Reports

I've noticed an increase in bug reports being filed over the last few days. While a few of these bug reports have been quite helpful, the vast majority of them lack significant and necessary information, which makes them less useful and causes additional confusion about what the bug really is. So I thought I would write a guide on how to provide a proper bug report for GravityBox, to help the new users to this thread, as well as provide a reference for the experienced users.

The aim of a bug report is to describe what went wrong in enough detail that the developer can reproduce it on his device. Describe everything in detail, be direct and clear. State what you saw, and also state what you expected to see. List all the steps to reproduce the problem. After you type out the steps, follow them yourself to ensure you haven’t left anything out. Don’t make any assumptions that the developer will know what you mean, if you haven’t written it out, then it didn’t happen.

If the developer can’t reproduce the problem, or at least identify what is causing it, then you’re probably not going to get a fix.

Be ready to provide extra information if the developer needs it. If he didn’t need it, he wouldn’t be asking for it. He isn’t being deliberately difficult. Providing version numbers of your device, ROM, Xposed, and GravityBox are the minimum. Don’t just say “the latest version”, actually provide the number. Sometimes an update is released since the last time you checked, so you may not actually be on the latest version. Providing the actual version numbers is the only way the developer can be sure of your device’s environment.

Many users think that by providing any type of bug report, even a very basic one, such as: "It doesn't work" is better than doing nothing. Give the developer some credit for basic intelligence: if GravityBox really didn’t work at all, he would probably have noticed. Since he hasn’t noticed, it must be working for him. Therefore, either you are doing something differently from him, or your device is different from his. He needs information; providing this information is the purpose of a bug report. More information is always better than less.

Be precise, developers like precision.

If a bug has already been reported, there is little reason to report it again, unless the developer specifically asks for more people to report it. When you post a "+1" message after someone else's bug report, all this does is add confusion to the thread and contributes nothing to the goal of fixing the bug. If you have no new information to provide, then don't post a bug report. If you can provide additional information that you think might help, then do post and link to the original bug report, and include your additional details, including all relevant details about your device if it’s different from what has already been reported.

Due to financial and technological constraints, developers can’t possibly own every device and ROM combination, which means there are a lot of users who have devices and ROMs that the developer has not used. This is important information.

Every bug report should always include the make and model of the device, the name and version number of the ROM.

An example such as, “Nexus 5 stock Android 4.4.4 build KTU84P.” Provide the device details upfront, the developer should never have ask for them, this is a basic detail that is always required. A bug may be specific to a particular device, or it may occur on different devices, but these details can make all the difference, and providing will usually result in you getting a fix sooner.

A bug report should always contain a log of the error.

There are a number of things going on in the background on your device that you don’t see but are relevant to the operation of GravityBox. A minor UI glitch might be nearly impossible to track down without a log, but by being able to read line by line in a log and seeing what happened, makes it a lot easier to find and fix the bug. Without a log, many bug fixes are like trying to find a needle in a corn field. Provide a verbose log, of only the time period where you reproduce the bug. These logs will likely contain hundreds if not thousands of lines, so please limit it as much as possible to the shortest time needed to reproduce the bug. Attach the log file to your bug report as a file attachment (.txt or .zip file), or paste it on a site like pastebin.com, and then include a link to it in your bug report. But please don't just copy and paste the entire logcat into your post in this thread, it causes posts to be unnecessarily long and difficult to read.

In summary, every single bug report should contain, at the minimum, the following information:

What happened: Describe the bug, what you saw, any error messages, force closes, UI glitches, etc.

What was expected: Describe what you expected to see.

Steps to reproduce the bug: Be thorough and detailed, don’t make any assumptions in the steps. List everything you do, from tapping an icon, changing a setting, turning down the volume, etc. This is the part where you can’t give too much information, more is always better.

Device environment: List your device’s make, model, ROM name and version, OS build if available, and the carrier name is sometimes helpful (if there are multiple different configurations of the same device).

Log file: Provide a logcat file of the steps where you reproduce the bug. Set the log type to verbose, and limit the duration to as short of a time as needed to capture the bug.

If you can’t provide all of this information, then please explain why. If you’re trying to get a logcat, but it errors out before running, explain that. It’s better to explain what is preventing you from providing a crucial piece of information, than to just omit it. A bug report that contains all of this information, or as much of it as possible, will go a long way to helping the developer recreate the bug on his end, determine what is causing it, and provide a fix for it, all in a timely fashion.

And always remember to be gracious and appreciative

of the developer for donating his time and effort to helping you. Developers on XDA do not get paid for their work, they do it all because they want to, on their own time and at their own expense. They owe nothing to anyone on this site. Even if you have donated to their project, they still owe you nothing more than anyone else. You donated because you wanted to contribute to the development of the project, not to buy any extra level of support.

Let’s help the developers help us, the users, by providing the necessary information they need, in the bug reports we post.

*Idea and portions of this post came from http://www.chiark.greenend.org.uk/~sgtatham/bugs.html and used under OpenContent license.

.