How to write a good bug report

Writing a good bug report is essential to help us fix your bug! While writing your bug report you should have exactly one goal: maximizing the chance of this bug to get fixed.

To reach this goal you absolutely need to include reproducible steps and be very specific/concise.

:warning: Security bugs

We take security very seriously. We welcome any peer review of our 100% open source code to ensure nobody’s Mycodo instance is ever compromised or hacked.

In order to give the community time to respond and upgrade we strongly urge you report all security issues privately. Please contact @KyleGabriel to provide details and repro steps and I will respond ASAP. If you prefer not to use the forum, contact directly at https://kylegabriel.com/contact with details and repro steps. Security issues always take precedence over bug fixes and feature work. We can and do mark releases as “urgent” if they contain serious security fixes.

:warning: You should always try to reproduce your bug with the latest version of the software. Always upgrade to the latest version to see if the bug has been fixed.

:warning: Bugs are more often than not about false assumptions, always question these assumptions, even in your bug report.

Priority/Severity: How fast does this bug needs to be fixed? Everyone wants everything to get fixed quickly but try to keep the emergency button for real emergencies.

Platform: Mycodo runs on multiple Raspberry Pi variants. You should always specify your test environment (Raspberry Pi hardware version, Raspbian OS version, etc.).

Description: Be as concise as possible, describe each problem separately if you think they don’t deserve their own bug report. Use simple words and remove anything which is not strictly about the report. We love writing paragraphs on a forum but this is not the place for it.

A simple way to write this is to think in terms of ACTUAL versus EXPECTED results, do not assume we know what you expected to see, write it.

Reproducible steps: A bug report should be reproducible, ensure you can repro it multiple times in a row. A seemingly random bug report could be acceptable if you can still repro it fairly often, let’s say at least one time out of ten. In this case, your report should be even more detailed.

For anything UI/UX related you should at least include a picture (or a video if a picture can’t capture the issue). It shouldn’t prevent you from writing the steps and be very descriptive about it. Once again, don’t assume we know anything about what you are talking about, Mycodo has many pages and thousands, if not millions, of possible configurations. It’s best to always start your steps from home screen.

Tone: Reading bug reports can be harsh for developers, especially for open source software they’re not paid to work on. You should try to keep a polite tone and not use the bug report to release any anger (I may be just as frustrated as you when I learn about a bug in my software). Writing like “this thing is broken again, who thought this would be a good idea?” or more generally any negative behavior will most likely lead to your bug report being ignored or treated with more delay.

Writing such a high quality bug report takes time. If you don’t have this time at hand, feel free to still open a bug report with limited description/steps, specifying you need more time to improve it. It might be enough to get it fixed.

Use your common sense to decide how exhaustive and descriptive your report needs to be for the bug at hand.

Thanks for your help :raised_hands:

2 Likes