From d19597d34e516a6c063c02fb4095e8cab91f03d1 Mon Sep 17 00:00:00 2001 From: corazonthedev Date: Fri, 19 Jun 2026 01:54:25 +0300 Subject: [PATCH] docs: refresh label catalog to match live taxonomy (#711) The labels.md was badly stale: documented 20+ labels that don't exist on the repo, used colon prefix (area:context) instead of slash (area/context), and was missing the priority/, complexity/, and milestone/ families entirely. Rewrite from the live label set (verified against gh label list): - 30 labels across 7 families - All area/* use slash form - Add gh label list command for keeping current - Note on commonly-used but unregistered labels --- docs/agent-context/labels.md | 169 +++++++++++++++-------------------- 1 file changed, 74 insertions(+), 95 deletions(-) diff --git a/docs/agent-context/labels.md b/docs/agent-context/labels.md index 888be219..4033dad9 100644 --- a/docs/agent-context/labels.md +++ b/docs/agent-context/labels.md @@ -1,104 +1,83 @@ -# Recommended GitHub labels for contextweaver - -> Labels live on GitHub, not in the repo. Maintainers create these -> through the GitHub UI or `gh label create`. This file is the -> authoritative recommendation for the set the project ships with -> and how each one is used. - -## Triage / status - -| Label | Colour suggestion | When to apply | -|---|---|---| -| `needs triage` | `#fbca04` (yellow) | New issue not yet looked at; remove once labelled and assigned. | -| `needs reproduction` | `#fef2c0` (light yellow) | Bug report missing reproduction steps. | -| `confirmed` | `#0e8a16` (green) | Bug confirmed by a maintainer. | -| `wontfix` | `#ffffff` (white) | Out of scope; explain why in the closing comment. | -| `duplicate` | `#cfd3d7` (gray) | Closed as duplicate of another issue. | -| `stale` | `#d4c5f9` (light purple) | No activity for 60+ days; will auto-close if unrelated. | - -## Type - -| Label | Colour | When to apply | -|---|---|---| -| `bug` | `#d73a4a` (red) | Reproducible defect. Existing label. | -| `enhancement` | `#a2eeef` (light blue) | New feature or improvement. Existing label. | -| `documentation` | `#0075ca` (blue) | README, docs/, examples/, or in-repo prose. Existing label. | -| `performance` | `#fbca04` (yellow) | Latency / throughput / memory regressions or wins. | -| `security` | `#b60205` (dark red) | Sensitivity, redaction, supply-chain, or auth. Treat private until triaged. | -| `breaking` | `#ee0701` (red-orange) | Affects public API; needs CHANGELOG migration note. | +# GitHub labels for contextweaver -## Area - -| Label | Colour | When to apply | -|---|---|---| -| `area:context` | `#c2e0c6` (light green) | `src/contextweaver/context/` — pipeline, manager, firewall, views. | -| `area:routing` | `#bfdadc` (teal) | `src/contextweaver/routing/` — catalog, graph, router, cards. | -| `area:adapters` | `#fad8c7` (light orange) | `src/contextweaver/adapters/` — MCP, A2A, FastMCP, providers. | -| `area:store` | `#c5def5` (light blue) | `src/contextweaver/store/` — EventLog, ArtifactStore, FactStore. | -| `area:cli` | `#fef2c0` (light yellow) | `src/contextweaver/__main__.py`. | -| `area:benchmarks` | `#d4c5f9` (light purple) | `benchmarks/` and `scripts/render_scorecard.py`. | -| `area:docs` | `#0075ca` (blue) | `docs/` and `README.md` (combine with `documentation`). | -| `area:integrations` | `#bfd4f2` (light blue) | `docs/integration_*.md`, integration tests, example scripts wrapping third-party SDKs. | - -## Contributor / agent friendly +> Labels live on GitHub, not in the repo. This file documents the +> canonical label set. Use `gh label list` for the live reference. -| Label | Colour | When to apply | -|---|---|---| -| `good first issue` | `#7057ff` (purple) | Existing label. Scoped, well-defined, no deep architectural context required. Each one should be claimable end-to-end in <2 hours. | -| `help wanted` | `#008672` (teal) | Maintainers would welcome an external contributor; might be larger than `good first issue`. | -| `agent-friendly` | `#5319e7` (deep purple) | Acceptance criteria are explicit, the surface area is small, no judgement calls are required. Suitable for Claude Code / Copilot Agent Mode / Codex. Add this in addition to `good first issue` where it applies. | -| `mentor available` | `#1d76db` (blue) | A maintainer has volunteered to guide the contributor in PR review. | +## Triage / Status -## Release +| Label | Description | +|-------|------------| +| `bug` | Something isn't working. | +| `documentation` | Improvements or additions to documentation. | +| `duplicate` | This issue or pull request already exists. | +| `enhancement` | New feature or request. | +| `good first issue` | Good for newcomers. Scoped, well-defined, no deep architectural context required. | +| `help wanted` | Maintainers would welcome an external contributor. | +| `invalid` | This doesn't seem right. | +| `question` | Further information is requested. | +| `wontfix` | This will not be worked on. | -| Label | Colour | When to apply | -|---|---|---| -| `launch` | `#5319e7` (deep purple) | Required for the public-launch release. | -| `release-blocker` | `#b60205` (dark red) | Must land before the next tag. | -| `release-notes` | `#f9d0c4` (peach) | Worth surfacing prominently in CHANGELOG / release notes. | - -## How to create these on GitHub +## Area -Using `gh label create` (assumes a logged-in `gh` CLI): +| Label | Scope | +|-------|-------| +| `area/adapters` | Protocol adapters: MCP, A2A. | +| `area/context` | Context engine: manager, pipeline, firewall. | +| `area/eval` | Evaluation, benchmarking, quality measurement. | +| `area/infra` | CI, builds, tooling, project infrastructure. | +| `area/observability` | Metrics, logging, debugging. | +| `area/routing` | Routing engine: catalog, graph, router, cards. | +| `area/store` | Data stores: event log, artifacts, episodic, facts. | + +## Priority + +| Label | Meaning | +|-------|---------| +| `priority/high` | High priority — closes a critical gap. | +| `priority/medium` | Medium priority — production readiness. | +| `priority/low` | Lower priority — scale & validation. | + +## Complexity + +| Label | Meaning | +|-------|---------| +| `complexity/simple` | Straightforward change, minimal risk. | +| `complexity/average` | Standard effort, moderate familiarity needed. | +| `complexity/complex` | Cross-cutting, significant design or risk. | + +## Milestone + +| Label | Target | +|-------|--------| +| `milestone/v0.2` | Core pipeline completion. | +| `milestone/v0.3` | Production readiness. | +| `milestone/v1.0` | Runtime modes + security. | +| `milestone/v0.4` | Observability & evaluation. | +| `milestone/v0.5` | Advanced routing & scale. | + +## Other + +| Label | Description | +|-------|-------------| +| `examples` | Example scripts and demo improvements. | +| `security` | Security-related: data leakage, access control, redaction. | +| `spike` | Time-boxed research or proof-of-concept. | + +## Note on issue-only labels + +Issues may carry labels not registered in the repo's label list +(e.g. `type:feature`, `type:task`, `priority: high` with colon +instead of slash, `good-first-ai-issue`, `blocked`, `needs-info`, +`reliability`, `developer-experience`). These are not canonical; +consider registering them via `gh label create` if they see +frequent use. + +## How to keep this file current ```bash -gh label create "needs triage" --color FBCA04 --description "Not yet triaged" -gh label create "needs reproduction" --color FEF2C0 --description "Bug report missing reproduction steps" -gh label create "confirmed" --color 0E8A16 --description "Bug confirmed by a maintainer" -gh label create "performance" --color FBCA04 --description "Latency / throughput / memory" -gh label create "security" --color B60205 --description "Sensitivity, redaction, supply-chain, auth" -gh label create "breaking" --color EE0701 --description "Affects public API" -gh label create "area:context" --color C2E0C6 -gh label create "area:routing" --color BFDADC -gh label create "area:adapters" --color FAD8C7 -gh label create "area:store" --color C5DEF5 -gh label create "area:cli" --color FEF2C0 -gh label create "area:benchmarks" --color D4C5F9 -gh label create "area:docs" --color 0075CA -gh label create "area:integrations" --color BFD4F2 -gh label create "help wanted" --color 008672 -gh label create "agent-friendly" --color 5319E7 --description "Suitable for Claude Code / Copilot Agent / Codex" -gh label create "mentor available" --color 1D76DB -gh label create "launch" --color 5319E7 -gh label create "release-blocker" --color B60205 -gh label create "release-notes" --color F9D0C4 -gh label create "wontfix" --color FFFFFF -gh label create "duplicate" --color CFD3D7 -gh label create "stale" --color D4C5F9 +# Dump live labels and regenerate the tables above +gh label list --json name,description --jq '.[] | "| \(.name) | \(.description) |"' ``` -Existing labels (already present on the repo): `bug`, `enhancement`, -`documentation`, `good first issue`. Do not recreate them. - -## Issue templates that auto-apply labels - -Templates under `.github/ISSUE_TEMPLATE/` set initial labels: - -| Template | Auto-applied labels | -|---|---| -| `bug_report.yml` | `bug` | -| `feature_request.yml` | `enhancement` | -| `integration_request.yml` | `enhancement`, `area:integrations` | -| `docs_improvement.yml` | `documentation`, `area:docs` | - -Triagers should add area / contributor-friendly labels manually. +Compare output against this file periodically (e.g. every quarter) +or when a new label family is introduced.