How to Write a Good Issue

A best practices guide for how to create issues.

Table of Contents


There is not one good way to write issues. But there are things we want to avoid that either will discredit what we want or need, or won't help the person who will try to solve the issue.

Some important things to remember:

A suggested solution can be a good thing, especially to help the contributors who have less experience. When you're writing issues on a repository that isn't your own, you might not have all of the context to provide the best solution. This is why, although suggestions are appreciated, the maintainers have the final say in the solution and/or approach to the issue.


Back to Top

Remember, there isn't one way to do it. We're going to walk you through how to create an issue, and reference the Virtual Coffee repository as an example.

  1. Go to a repository. Let's check out Virtual Coffee repository
  2. Navigate to the Issue Tab
  3. Check is if there is an available template. You can find this by clicking the New Issue button on a repository.
    • In repos that are used to get a lot of traffic and issues, there is often an automatic template that appears when you create the issue. In that case, follow exactly the steps and requirements.
  4. If there are no specific rules, here is a list of what's good to share in different types of issues:

Back to Top