What are Issues?¶
Issues are tickets that allow us to manage all the suggested features, bugs noticed and discussions about a project.
An Issue ticket should have a simple, easy to understand title and a clearly written description outlining any of the available details. Once an Issue is created, people can comment on it and if work is to be actioned due to it, it can be assigned to a contributor so others know that it's being worked on already.
How do I make an Issue?¶
Before making an Issue, search the existing ones! Often, an Issue ticket already exists within the scope of what you might be considering, so be sure to do a search beforehand and if there it, add any new information or suggestions to the comments on the existing Issue instead, or just add a thumbs up if you agree with it.
If you don't see one existing, then:
Issuestab in a repository:
Enter the title and description for your issue, then click
Submit new issue:
What should I put as a title?¶
A good title is short and to the point as to what the Issue is about.
Avoid some of the following:
- Writing a long title
- Being too vague
- Using informal language
- Using languages other than English
What makes a good description?¶
A good description is well structured and contains all the information available to you at the time of creating it. If additional information comes to light, it can either be added in edits to the description afterwards, or as part of comments.
Try to avoid:
- Masses of unstructured blocks of never ending text
- Including unnecessary details that aren't constructive to the discussion
Definitely try to:
- Include relevant images in the description if it involves visual aspects
- Make use of Github's markdown syntax for text formatting
What are labels?¶
Labels allow us to better organise Issues by letting us view what type of Issue it is, how it might impact the codebase and at what stage it's at.
In our repositories, we try to prefix labels belonging to the same group, for example the label groups
type. We will be trying to keep to the same general structure across our project repositories, but just have a look at the full labels list in the respective repository to get a clear idea what's available.
If you're a contributor, you can add relevant labels yourself to any new Issue ticket you create.
General label groups¶
These label groups should be present on most of our main project repositories and can serve as a guide as to how they're used.
Signifies what section of the project/codebase the Issue is focusing on addressing or discussing. Only one area should be selected usually, as the most focused area should be the selected one. Exceptions exist for Issues that impact multiple areas equally, but are generally not the norm.
How urgent the Issue should be addressed:
critical- Super important, likely a bug that's impacting the project severely at this moment.
high- Important, impacts the project heavily and/or is time sensitive.
normal- Would be convenient if it's addressed.
low- Doesn't require us to look at any time soon.
Where this issue is at currently:
deferred- Is being put off until a later date
planning- The Issue is being discussed, implementation is not decided or ready to begin.
stale- Hasn't been addressed or contributed to in a long time. Worth reconsidering as worth keeping open or bumped in priority if it needs to be done to get it out.
stalled- Something else has prevented this Issue from moving forward for now.
WIP- The issue is actively being worked on by someone already.
What's the purpose of the Issue:
bug- Addresses a bug in the code
enhancement- Changes or improves on an existing feature.
feature- Addresses a possible new feature.
question- Isn't addressing any code changes, only a discussion or clarification.
There are 4 labels that aren't in groups as they are globally recognised and shouldn't be renamed:
duplicate- Marks the Issue as being the same or within scope of an existing one
good first issue- Marks the Issue as being suitable to work on by beginners
help wanted- More people are needed to work on this Issue
invalid- Marks the Issue as not being a proper Issue.
Once an Issue is not in the planning/discussing stage and is approved to be worked on, it can be assigned to someone interested in it.
Can I assign myself?¶
Only staff can assign themselves to a ticket. If a general contributor assigns themself, they'll be unassigned.
How do I get assigned?¶
First check that someone else isn't already assigned.
Once you're sure it's available and ready to be worked on, you can leave a comment in the Issue ticket. Generally, it's first-come first served, so a staff member will usually assign you within the day if they confirm it's clear to do so.
Do I get first preference to work on it if I made the Issue ticket?¶
As long as you say you'd like to work on it within the description of your ticket or be the first to request so in a comment. If you forget to say so and someone else asks to be assigned, we aren't likely to unassign them afterwards, so it's entirely up to the discretion of the other person in that case.