Writing 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 have a specific workflow

:warning: You should always try to reproduce your bug with safe mode unless you already know the issue is coming from a customisation.

: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: If possible always try multiple platforms for UI bugs. In any case you should always specify your test environment (desktop/mobile/touchscreen/tablet, OS, OS version…).

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 Discourse 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, a video being the best solution. 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, Discourse has hundreds of screens and thousands of features, always start your steps from home screen.

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. Terms like: this thing is broken again, who thought this would be a good idea?.. Or more generally any toxic behaviour will most likely lead to your bug report being ignored or treated with more delay.

Priority/Severity:

Platform:

Description:

Reproducible steps:

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:

37 Likes

Awesome post! :+1:

Some quick points of feedback, if I may;

  • Since this post was written, new topics have begun defaulting to #general. This isn’t intuitive for those using the post template, so it might be worth specifically suggesting that they change it to #bug. Otherwise they may not think of checking, and assume the template will default to the right place (which I assume it isn’t capable of doing - would be nice if it was, though!).
  • I wonder if it would be worth reworking the post so that most of the text is not part of the template. As-is it leaves one with a lot to remove, which is a bit of a clunky experience.

Something like this, for example;

Priority/Severity:

Platform:

Description:

Reproducible steps:

Use template as new topic

5 Likes

Good points :+1: I made the changes.

4 Likes