An issue is a story explaining why something should be changed. It serves as the seed for collaboration in order to get it solved.
Issues can be of two types:
- Bug: something that isn’t as it is supposed to be, this is broken
- Enhancement: an improvement that could be done to make something better
The goal of an issue is to provide knowledge about and context on what to fix or improve. You can make issues alone or together.
An issue can contain a proposed fix, but does not have to.
Raise one point per issue, and try avoid negations in the issue title.
We write good issues because:
- it helps communicate things that need to be done
- planning becomes easier if you understand the context of a change
- the person filing an issue is not always the person to fix it - they might have different skillsets
- commit messages become better with more context
Structure
The title of the issue should be short, to the point and descriptive. Enhancements can have verbs in them. Detail, technical or otherwise, should be in the body of the issue.
- Context: why are you filing this issue
- Problem or idea and what will be different when this issue is resolved
- Solution or next step: request feedback from others, propose changes or propose further investigation
Defining done for issues
It’s helpful for the person who solves the issue to know when they’ve actually fixed it. List multiple steps or actions with checkboxes so they can be tracked and resolved.
Writing a bug
A bug is something that is wrong. In order to clearly communicate what is wrong it helps to answer the following questions:
- What did you try to do or find out
- What did you expect
- What did you find
Writing an enhancement
An enhancement is something that could be better. In order to understand what the enhancement really is it can help to specify:
- a motivation: what users will benefit from this
- a description of how you envision this to be or how you would solve this
Tag relevant contributors and other issues
Context is key, so use the GitHub functionality of tagging other contributors when relevant as well as mentioning other issues and pull requests.
Add labels to issues to help keep overview
Standard labels include bug, enhancement, help wanted, duplicate and good first issue.
Apart from these different codebases can have labels specific to them.
For example for prioritization or team assignment.
Make your issue a good first issue
Issues labeled good first issue provide an easy way for new contributors to get into committing.
A good first issue describes the issue and provides step by step instructions on how to resolve it or alternatively a clear description of the solved state.
If you have an issue that is easy to resolve, consider explaining how to do that so it can be fixed by someone new to the community.
Closing an issue
An issue can be closed if it:
- is something that can’t be worked on right now
- isn’t a current priority
- has been resolved in some other way
Closed issues stay available and will turn up in search results so that people can see that it has been considered and the conversation will stay available.
Closing an issue doesn’t mean that this issue is never to be solved, but that it doesn’t have a place in the shared backlog right now.
The issue list
Every repository has a list of issues. We use the list of issues to:
- understand what needs to be done
- prioritize what to do
- collaborate with each other on finding solutions
- help new contributors find out how they can contribute