How to write a good bug report ๐Ÿ›

First of all, thank you for wanting to file a bug report! While writing your bug report you should have exactly one goal: Maximizing the chance of this bug getting fixed. Writing a good bug report is essential to helping us make that happen!

The most important thing is, we need you to include reproducible steps and be very specific/concise.

:warning: Security-related bugs have a different workflow. Please visit our Bluescape Vulnerability Disclosure Policy for more details. Do not file security-related issues here.

:warning: Keep in mind bugs are generally about false assumptions. Always question these assumptions, even in your bug report.

Priority/Severity: Please be honest on this. How fast does this bug need to be fixed? The emergency button is for real emergencies. We do understand that right now, this is an emergency for you.

Description: Be as concise as possible, describing 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.

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 in detail.

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

Tone: Reading bug reports can be harsh for developers. You should always keep a polite tone and not use the bug report to release any anger. Keep your bug report to the facts and donโ€™t editorialize. Phrases like โ€œthis thing is broken againโ€, or โ€œwho thought this would be a good idea?โ€ may feel good to you, but please keep it professional.

Writing a high-quality bug report takes time. If you donโ€™t have the time, feel free to still open a bug report with limited description/steps. Explain that you need more time to improve the report. It still might be enough to get it fixed.

Thank you for your help!

3 Likes