At TailorDev, we are (still) big fans of GitHub , even though GitLab is amazing month after month. As a remote-first company , how we communicate is really important, and we continuously test new ideas and tools to improve our communication. In this first article of a two article series, we share the way we manage GitHub issues with labels .

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).

Zero-Bug Labels

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).

critical

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…

bug

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.

improvement

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.

feature

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).

Status Labels

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.

needs help

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.

needs test

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.

needs doc

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.

needs review

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.

Meta Labels

question

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

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.

feature request

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.

TailorDev

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.

Conclusion

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!