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.
- 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
- Avoid superfluous labels that communicate information which is readily apparent (e.g.
- An issue or pull request should not require a label indicating that it requires action à la
- 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.
- 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.
Generally, labels across most critical repositories in the WooCommerce organization in fall into one of several purposes. They can indicate the:
- type: such as
- status: such as
- category: such as
- priority/impact: such as
- planning metadata: such as
scale: large, or
- next action: such as
needs design feedback,
- workflow considerations:
needs cherry picking,
status: testing instructions added, or
- 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.