Some guidelines:
- Read the documentation. Then read it again. Seriously, I can’t count how many times I’ve had an issue that the documentation addressed already.
- Search through existing issues. Often, someone has already reported the same problem. If you’re lucky, a fix might be ready to test already! Only comment if you’re absolutely sure your issue is the same one being described, however.
- Read the guidelines for bug reports, if any. Larger projects and prolific maintainers may have specific guidelines to ensure they’re getting the data they need. Following them helps both of you—very often, they can’t help if you don’t.
- Be thorough. If the maintainer offers a template for bug reports, use that. If they don’t, you’re welcome to borrow the one below.
Sample Bug Report Template
Title
Make sure the title of your issue is descriptive of the actual problem.
Summary
Provide a summary of the issue. Try to keep it brief.
Steps to Reproduce
This is often the most important part. Offer detailed steps to reproduce the issue.
Expected Behavior
Explain what you expected to happen after following these steps.
Actual Behavior
Explain what actually happened instead.
Reproducible
Once you’ve reproduced the behavior, run through the steps again, a total of five times. Count the number of times the behavior was exhibited. I typically express this as a fraction (5/5 when I’ve tried to reproduce the bug five times, and was successful each time).
Additional Information
Any other relevant context should go here.
Attachments
Sometimes you’ll be asked to include logs or config files. Make sure they’re provided here, with any secrets redacted.