Writing an effective bug report

:bookmark: This is a guide for writing effective bug reports in Discourse to maximize the chances of getting bugs fixed.

:person_raising_hand: Required user level: Any can report a bug

Writing a good bug report is essential to help the Discourse team fix issues efficiently. This guide will walk you through the steps and best practices to ensure your bug report is clear, concise, and actionable.


In this documentation, we’ll cover:

  • The importance of providing reproducible steps and specific details
  • How to describe the problem and expected behavior
  • Best practices for reporting on different platforms
  • Maintaining an appropriate tone in your report
  • Common pitfalls and solutions

Steps to writing an effective bug report


Determine the urgency of the bug fix. While everyone wants their issues resolved quickly, reserve the highest priority for critical issues that significantly impact functionality.


Always specify the environment on which the bug was observed. This includes:

  • Device type (desktop, mobile, touchscreen, tablet)
  • Operating System and its version
  • Web browser and its version

Where possible, replicate the bug across multiple platforms to confirm its presence.


Be concise. Describe the issue simply and without unnecessary detail. Separate different problems if they can be reported individually. A clear description format includes:

Actual Result: What is happening?
Expected Result: What should have happened?

Avoid assumptions about what the reader already knows. Be explicit about what should have been seen or occurred.

Reproducible steps

Ensure the bug can be reproduced consistently. Write step-by-step instructions starting from the home screen of Discourse. If the bug appears randomly, specify how often it occurs (e.g., 1 out of 10 attempts). For UI/UX-related bugs, add screenshots or videos for clarity.


Maintain a respectful and polite tone. Avoid using the bug report to express frustration. Any toxic language or behavior can result in your report being delayed or ignored.


Use this template to quickly start a new bug report topic:




Reproducible steps:

Best Practices

  1. Reproduce in Safe Mode: Before reporting, try to reproduce the issue in Discourse’s Safe Mode if you suspect customizations might be causing it.
  2. Question Assumptions: Bug reports often stem from false assumptions. Even in your report, question and clarify any assumptions you might have.
  3. Be Detailed: For elusive or rare bugs, provide as much detail as possible. Include anything you think might be related, like error messages or log files.

Common Issues and Solutions

Issue: Unable to reproduce the bug consistently.
Solution: Document the environment and conditions under which the bug appears. Note any patterns or commonalities.

Issue: Lack of response to a bug report.
Solution: Ensure your report is detailed but concise and written in a courteous tone.


Q: What if I don’t have time for a detailed report?
A: It’s still helpful to open a report with the information you have. Indicate that you will update it with more details later.

Q: Where should I post my bug report?
A: Use the appropriate category - bug reports should go in the bug category.

Additional Resources

Last edited by @hugh 2024-06-11T03:05:22Z

Last checked by @hugh 2024-06-11T03:05:27Z

Check documentPerform check on document: