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


Make sure the title of your issue is descriptive of the actual problem.


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.


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.


Sometimes you’ll be asked to include logs or config files. Make sure they’re provided here, with any secrets redacted.