This is a guide for writing effective bug reports in Discourse to maximize the chances of getting bugs fixed.
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.
Summary
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
Priority/Severity
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.
Platform
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.
Description
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.
Tone
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.
Template
Use this template to quickly start a new bug report topic:
Priority/Severity:
Platform:
Description:
Reproducible steps:
Best Practices
- Reproduce in Safe Mode: Before reporting, try to reproduce the issue in Discourse’s Safe Mode if you suspect customizations might be causing it.
- Question Assumptions: Bug reports often stem from false assumptions. Even in your report, question and clarify any assumptions you might have.
- 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.
FAQs
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
- Creating bug reports for Discourse on Meta
- Use Safe Mode to troubleshoot issues with themes and plugins
- Security Bugs Workflow
Last edited by @hugh 2024-06-11T03:05:22Z
Last checked by @hugh 2024-06-11T03:05:27Z
Check document
Perform check on document: