first version of the knowledge base :)

70 - Tools/github/repository-labeling-strategies.md

@@ -0,0 +1,124 @@
+---
+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)