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!

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

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

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 concise as possible, describing each problem separately if you think they don’t deserve their bug report. Use simple words and remove anything which is not strictly about the report.

A simple way to write this is to think about ACTUAL versus EXPECTED results. Please do not assume we know what you expect to see. Write it in detail.

Reproducible steps

A bug report should be easily re-created and reproduced multiple times. 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. It would be best to 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, but please keep it professional.

Writing a high-quality bug report takes time. If you don’t have the time, feel free to open a bug report with limited description/steps – try to write it to the best of your ability. Explain that you need more time to improve the report. It still might be enough to get it fixed!

Thank you for being so helpful!

Where to Next?

Not what you were looking for? Reply below or Search the community and discover more Bluescape.

3 Likes