Adopting Standardized Labeling Principles

As the number of developers building with WooCommerce continues to grow rapidly, we’re putting an increasing amount of effort into measures that will provide an easier onboarding experience for developers who are new to the platform and which will reduce the development friction for seasoned WooCommerce veterans. One recent initiative we’ve undertaken is an effort to standardize the labeling system we use for tracking work on our most critical repositories.

The WooCommerce organization on GitHub is home to nearly 150 different open source repositories maintained by over a dozen different teams. These repositories contain not only WooCommerce’s core code base but also many interdependent extensions, packages, libraries, and other tools. In addition to the internal engineering teams who maintain these repositories, there are also developers from our external community, Happiness Engineers, and many automated workflow tools that need to traverse and interact within repositories. By standardizing the taxonomy around the GitHub labels that categorize and track the work on these repositories, we can make it much easier for everyone to navigate the WooCommerce organization.

The goal of this initiative is not to mandate that all of these repositories use the exact same set of labels but rather establish a shared set of principles and predictable patterns for labels.

Labeling Principles

• Since labels are meant to communicate information, often at a glance, they should be explicit, clear, and concise.
• Use verbs to indicate that a particular action needs to be taken or has been taken. (e.g. instead of tests, use needs tests or includes tests)
• Avoid superfluous labels that communicate information which is readily apparent (e.g. pr-merged is superfluous).
• An issue or pull request should not require a label indicating that it requires action à la needs-action.
• Labels should be written in lowercase and should be regular words separated by spaces. Hyphens and other ad-hoc separation characters are unnecessary.
• Structured labels, however, are encouraged because they provide additional context. Structured labels should use a colon and a space as a delimiter to create a key-value pair (e.g. type: bug).
• Labels should all have a clear description of what the label’s purpose is.
• Label colors should be chosen with accessibility in mind, not only for the label itself but also with respect to other labels that it is likely to appear alongside.
• To ensure we continuously maintain labels, their maintenance should be easy. With that in mind, a repository’s maintainers should take care not to create a tedious number of labels to account for every scenario.
• Always be iterating. It should be easy to experiment with adding, editing, or removing a label without disrupting the broader system.

Label Purposes

Generally, labels across most critical repositories in the WooCommerce organization in fall into one of several purposes. They can indicate the:

• type: such as bug or enhancement request
• status: such as blocked or in progress
• category: such as performance, Checkout Block
• priority/impact: such as critical, high, or low
• planning metadata: such as epic, needs scoping, scale: large, or estimate: 5
• next action: such as needs design feedback, needs discussion
• workflow considerations: needs cherry picking, cherry picked, status: testing instructions added, or involves happiness
• community instructions: good first issue

This list is not exhaustive and there is admittedly some grey area, but these are the general trends we identified as we inspected repositories. With that in mind, we have adopted a truncated version of this list containing following set of labels:

Putting it into practice

Keeping with the principles outlined above, this is meant as an initial iteration of a system that will evolve over time to meet the needs of the folks who build with WooCommerce. It is also meant to serve as a stylistic foundation upon which maintainers can build additional labels tailored to the work happening in their respective repositories.

The standardized set of labels is also maintained in an open source repository of its own and is something developers can run as a GitHub Action to keep their labels in sync with the standard set. If you want to take a look at the repository label synchronizer, it’s available at: https://github.com/woocommerce/woo-std-labels.

Don’t hesitate to reach out to us in the comments section below or in the #developers channel of our WooCommerce Community Slack.