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 to get 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 more often than not about false assumptions, always question these assumptions, even in your bug report.

Priority/Severity : Please be honest on this one: how fast does this bug needs to be fixed? The emergency button for real emergencies, though we understand that right now this is an emergency for you.

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.

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 reproduce it multiple times in a row. A seemingly random bug report could be acceptable if you can still reproduce it fairly often, let’s say 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, please. Phrases like “this thing is broken again”, or “who thought this would be a good idea?” may feel good to you, but are not helpful.

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.

Thanks for your help!

2 Likes