Our main classification is adapted from the Zero-Bug Software Development methodology, which describes a simple, clear yet very strict classification. We found this article very useful to formalize our former issue classification. Along with the four main types of the Zero-Bug policy (critical issues, bugs, features, and improvements), we also have status and meta labels. The status labels are used to quickly determine what is blocking on a Pull Request, while the meta labels are useful to flag issues with common terms (e.g., easy pick issues).
As introduced previously, we derived four of our default labels from the Zero-Bug Software Development classification. Those four labels are our main labels to sort issues. Let’s review them one by one, explaining why an issue may belong to a given type, and how to resolve it (as it is presented in the Zero-Bug Software Development article).
Classification: consumers are no longer receiving the value they are entitled to, or money / time is being wasted at an unacceptable rate.
Resolution: stop what you are doing, and fix the issue immediately. By now, we did not use this scary label, but we never know…
Classification: the system is not behaving as specified, but consumers are able to receive the value they are entitled to; or the rate of money / time wasted resulting from the issue is acceptable for the short-term.
Resolution: finish what you are doing, and then fix it.
Classification: an enhancement to an existing functionality or system. We can only improve something that is already part of the project. Otherwise, it is a new feature.
Resolution: work on these in the backlog priority order. Most of the time, we use a Kanban-like dashboard with Backlog / To do / Doing / Done columns. Improvements automatically fall into the Backlog one, and we decide what goes to the To do list for each sprint.
Classification: new functionality that does not yet exist in the project.
Resolution: this is very similar to the previous resolution, related to improvements. Features add value to the project or system, while improvements reduce the technical debt (which also adds value by the way).
Our (yellow) status labels are applied to Pull Requests (PRs), with the aim of indicating what is blocking and prevents the PR to get merged.
Classification: the contributor who initiated the Pull Request cannot complete her work. It can be because she has a design question, a problem with the API responses she is supposed to consume, anything.
Resolution: get in touch with the contributor to help her as soon as possible. This is the kind of label we do not like to see for too long.
Classification: the Pull Request either lacks tests or some important scenarios/edge cases are not covered enough.
Resolution: thanks to the recent GitHub changes, it is now possible to “lock” a Pull Request and to request changes. At TailorDev, any feature is made of code, documentation and tests. No exception. This label is resolved as soon as the reviewer(s) and the contributor(s) agree on the tests shipped within the PR.
Classification: the Pull Request does not provide documentation changes.
Resolution: this is very similar to the previous resolution, related to tests. This label is resolved as soon as the reviewer(s) and the contributor(s) agree on the documentation shipped within the PR.
Classification: the Pull Request is ready for review.
Resolution: anyone can review a Pull Request. Again thanks to the brand new GitHub reviewing system, a reviewer can choose to comment, approve or lock a PR. It is the reviewer’s responsibility to remove this label on the PR.
We do not flag all issues with all possible types of issue, but this label is quite useful to indicate that an issue requires an answer to a question.
Easy pick issues are very important to us because we want to encourage contributions and we are willing to help newcomers to start in Open Source.
In our Open Source projects, we label the ideas of external people as “feature requests”, which we distinguish from feature. A feature is a functionality that has been validated and will eventually be added. A feature request is a functionality that has not yet been validated, hence there is no plan to integrate it. Validating a functionality means accepting to add it to the project at some point.
In our Open Source projects, we feel responsible for some (internal) parts of them. Sometimes, we mark an issue with this special label, indicating that we will put effort on it or that we do not want to bother someone else.
We presented twelve default labels we use in most of our projects, four of them being heavily inspired by the Zero-Bug Software Development, four others used to define statuses on Pull Requests, and the last four for communicating common intents.
For consistency, we have a configuration file for the label names and colors, and we use github-labels to automate the creation of these labels on all projects. Along with these labels, we also have custom ones depending on the projects, e.g., for the different components. To visually distinguish them, we tend to use muted colors.
In the next article, we will introduce the way we write clear, factual and informative issues, pull requests, and comments on GitHub. Meanwhile, reach us on Twitter to share how you use GitHub labels! We would love to improve our current setup based on what works well for you!