Skip to main content

How to Write a Good Issue

What are issues?​

Issues are a way to list and keep track all the tasks that need to be done in a GitHub repository. Whether they identify a bug, or announce a project of feature, issues can be created by anybody. Although they are managed by the repository maintainer (aka the person or group in charge), they can be created by contributors and non-team members. And contributors don't need to have the answer! You only need to give a clear description of the bug, feature request, or the purpose of the issue..

2 quick examples:

  • As a maintainer, I know my app needs an update button in the profile page. I will create an issue to remember it, and it will help me plan my next deployment.
  • As a user, I love/use the app, and I think it would be even better without this annoying bug when I log in. I will create an issue to let the maintainer know about this problem.

Anybody can create issues in a repo--whether you have a suggested solution or not--but only the maintainers can manage them.

Important things to know​

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

Some important things to remember:

  • Provide facts. An issue needs facts, which can include pictures, metrics, and more. It is easier to explain than just using words.
  • Describe the issue by following any templates provided by the organization and/or asking yourself What, Where, When, How and Why.
  • Don't solve the issue. You are not expected to solve the issue. It happens of course, but it's important that the issue is clearly describes so that anyone can understand it without being in your head :)

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.

Tips Before Writing an Issue​

  • Check the repository's ReadMe and Contributing.md guide if they have one, to learn about how the project expects communication and issues to be created. For example, some repositories require you to start a discussion before making an issue.
  • Check current issues and closed issues to make sure no one has already written the issue you're going to write.
  • If the organization has discussions enabled, check to see if it's been mentioned there as well.
  • Check the Code of Conduct (COC) to make sure you participate in a way that's consistent with the organizations guidelines. Absence of a COC is unfortunate but doesn't mean people should be rude or disrespectful, even if the issue is "super frustrating."

How to write an issue?​

Remember, there is not only 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 VirtualCoffee.io 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:

Bug Issue:

  • A title that is clear enough to identify in few words what the problem is about.
  • Screenshots of the issue is in the UI, logs if it's a performance issue, or anything that proves the existence of the problem.
  • Your setup: type of device and OS version, type of browser and version, any kind of setup that can help reproducing the problem.
  • Description of how to reproduce the bug / behavior (the buttons you clicked, the request you've made, ...)
  • If you think of a solution to solve the problem, you can suggest something. Remember that your solution may not be the best solution for that specific issue / techno / repo...
  • Links to any issue or discussion that relates to this issue

Feature Issue:

  • A title that is clear enough to identify in few words what the problem is about.
  • Context for the issue: Describe the feature request.
  • Proposed Solution: What do you think the solution should be and why? If you don't have a suggestion, that's fine too!
  • Alternatives Considered: If you have thought about other solutions, what have you thought about and why did you think they weren't the best solution to the request?
  • Links to any issue or discussion that relates to this issue

Doumentation Change

  • A title that is clear enough to identify in few words what the problem is about.
  • Context for the issue: Describe the documentation request. - For example, "I noticed an unclear explanation of how to install the software. I encountered an some issues myself."
  • Proposed Solution: What do you think the solution should be and why? If you don't have a suggestion, that's fine too!

Other Resources​