How to label an issue
Issue labels are a tool in GitHub that that is used to group issues into one or more categories.
Gatsby is a very active project with many new issues opened each day. Labelling issues helps by identifying:
- good issues for new contributors to work on
- reported and confirmed bugs
- feature requests
- duplicate issues
- issues that are stalled or blocked
Anyone who’s a member of the Gatsby Maintainers team can label issues.
NOTE: If you’ve already had a pull request merged and you have not been invited to the maintainers team, please go to the dashboard and request a discount code. You should get an invite to the team — and you get free Gatsby swag! If that doesn’t work, please email email@example.com and we’ll get you invited.
Ideally, every issue should have a single
type: label applied to it. Optionally a
status: label or other labels may also be applied.
Before continuing, get familiar with Gatsby’s issue labels and their descriptions.
The broad steps to labelling an issue are:
- Read an issue
- Choose the labels that apply to that issue
- That’s it - sit back and relax, maybe take a few moments to enjoy the satisfaction of a job well done
The rest of this document will describe how to choose the right labels for an issue.
Read the issue and any comments to understand what the issue is about.
Choose a type label from the labels dropdown to the right-hand side of the issue.
You can check through the label descriptions for more information on each one.
The most common type of issue is
type: question or discussion, typically you can apply this to issues that are open-ended or have no clear next step.
It’s OK to change the type of an issue as more information becomes available. What starts as
type: question or discussion, might later need to be changed to
Changing labels is quick and easily reversible, so don’t worry too much about applying a “wrong” label.
Choose an appropriate
type: label and you’re ready to move on to the next step.
Check through the
status: labels (and their descriptions), if any apply to this issue add them as necessary.
Examples of applying
status: labels might be:
An issue that depends on an external dependency being changed could be labelled with
An issue with a clear description of how it can be resolved could be labelled
status: help wanted.
An issue that’s missing information required to help the author could be labelled with
status: needs more info
An issue describing a bug without clear steps to reproduce could be labelled with
status: needs reproduction
An issue describing a bug where there are steps to reproduce the bug and you’ve run the code locally and seen the error yourself can be labelled
There are a few other labels that can sometimes be applied to an issue. Here are some more examples of when to use them:
good first issuecan be used when an issue is a small, clearly defined piece of work that could be completed by someone without in-depth knowledge of Gatsby and how it works. These issues are particularly suitable for people making their first open source contributions.
stale?can be used on an issue where the author has not replied to requests for further information in at least 20 days.
And you’re done! You can call it a day or go back to the first step to label another issue.
Labelling issues is a great way to help out on the Gatsby project regardless of your experience level.