125 lines
3.1 KiB
Markdown
125 lines
3.1 KiB
Markdown
---
|
|
title: Repository Labeling Strategies
|
|
description: A practical GitHub label taxonomy for issues and pull requests
|
|
tags:
|
|
- github
|
|
- devops
|
|
- workflow
|
|
category: tools
|
|
created: 2026-03-14
|
|
updated: 2026-03-14
|
|
---
|
|
|
|
# Repository Labeling Strategies
|
|
|
|
## Introduction
|
|
|
|
Labels make issue trackers easier to triage, search, automate, and report on. A good label system is small enough to stay consistent and expressive enough to support planning and maintenance.
|
|
|
|
## Purpose
|
|
|
|
This document provides a reusable label taxonomy for:
|
|
|
|
- Bugs and incidents
|
|
- Features and enhancements
|
|
- Operations and maintenance work
|
|
- Pull request triage
|
|
|
|
## Architecture Overview
|
|
|
|
A useful label strategy separates labels by function instead of creating one long undifferentiated list. A practical model uses these groups:
|
|
|
|
- Type: what kind of work item it is
|
|
- Priority: how urgent it is
|
|
- Status: where it is in the workflow
|
|
- Area: which subsystem it affects
|
|
- Effort: rough size or complexity
|
|
|
|
## Suggested Taxonomy
|
|
|
|
### Type labels
|
|
|
|
- `type:bug`
|
|
- `type:feature`
|
|
- `type:docs`
|
|
- `type:maintenance`
|
|
- `type:security`
|
|
- `type:question`
|
|
|
|
### Priority labels
|
|
|
|
- `priority:p0`
|
|
- `priority:p1`
|
|
- `priority:p2`
|
|
- `priority:p3`
|
|
|
|
### Status labels
|
|
|
|
- `status:needs-triage`
|
|
- `status:blocked`
|
|
- `status:in-progress`
|
|
- `status:ready-for-review`
|
|
|
|
### Area labels
|
|
|
|
- `area:networking`
|
|
- `area:containers`
|
|
- `area:security`
|
|
- `area:ci`
|
|
- `area:docs`
|
|
|
|
### Effort labels
|
|
|
|
- `size:small`
|
|
- `size:medium`
|
|
- `size:large`
|
|
|
|
## Configuration Example
|
|
|
|
Example policy:
|
|
|
|
```text
|
|
Every new issue gets exactly one type label and one status label.
|
|
High-impact incidents also get one priority label.
|
|
Area labels are optional but recommended for owned systems.
|
|
```
|
|
|
|
Example automation targets:
|
|
|
|
- Auto-add `status:needs-triage` to new issues
|
|
- Route `type:security` to security reviewers
|
|
- Build dashboards using `priority:*` and `area:*`
|
|
|
|
## Troubleshooting Tips
|
|
|
|
### Too many labels and nobody uses them
|
|
|
|
- Reduce the taxonomy to the labels that drive decisions
|
|
- Remove near-duplicate labels such as `bug` and `kind:bug`
|
|
- Standardize prefixes so labels sort clearly
|
|
|
|
### Labels stop reflecting reality
|
|
|
|
- Review automation rules and board filters
|
|
- Make status changes part of the pull request or issue workflow
|
|
- Archive labels that no longer map to current processes
|
|
|
|
### Teams interpret labels differently
|
|
|
|
- Document label meaning in the repository
|
|
- Reserve priority labels for response urgency, not personal preference
|
|
- Keep type and status labels mutually understandable
|
|
|
|
## Best Practices
|
|
|
|
- Use prefixes such as `type:` and `priority:` for readability and automation
|
|
- Keep the total label count manageable
|
|
- Apply a small mandatory label set and leave the rest optional
|
|
- Review labels quarterly as workflows change
|
|
- Match label taxonomy to how the team searches and reports on work
|
|
|
|
## References
|
|
|
|
- [GitHub Docs: Managing labels](https://docs.github.com/issues/using-labels-and-milestones-to-track-work/managing-labels)
|
|
- [GitHub Docs: Filtering and searching issues and pull requests](https://docs.github.com/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests)
|