Skip to content

docs: refresh label catalog to match live taxonomy #715

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
corazonthedev wants to merge 1 commit into
base: main
Choose a base branch
from
+74 −95
Open

docs: refresh label catalog to match live taxonomy #715

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 74 additions & 95 deletions docs/agent-context/labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading