wehub-resource-sync
200 lines
5.6 KiB
Markdown
200 lines
5.6 KiB
Markdown
---
|
||
summary: "Issue labeling policy for triage, prioritization, and backlog hygiene."
|
||
read_when:
|
||
- Triageing GitHub issues
|
||
- Adding or updating issue labels
|
||
- Organizing the backlog
|
||
---
|
||
|
||
# Issue labeling guide
|
||
|
||
This repo uses labels to make the issue tracker easier to scan by:
|
||
|
||
- **type** — what kind of issue is this?
|
||
- **priority** — how urgent is it?
|
||
- **area** — what subsystem is affected?
|
||
- **provider** — which provider/service is involved?
|
||
- **workflow state** — what kind of follow-up is needed?
|
||
|
||
The goal is not to perfectly label everything. The goal is to make open issues easy to sort into:
|
||
|
||
- what is broken now,
|
||
- what needs maintainer attention,
|
||
- what is accepted backlog,
|
||
- and what belongs to a specific provider or subsystem.
|
||
|
||
## Labeling rules
|
||
|
||
For most open issues, aim to apply:
|
||
|
||
- **1 type label**
|
||
- **1 priority label**
|
||
- **1 workflow label**
|
||
- **1 area label**
|
||
- **0–1 provider labels**
|
||
|
||
That means most issues should end up with **3–5 labels max**.
|
||
|
||
## Type labels
|
||
|
||
Use the existing GitHub-style labels:
|
||
|
||
- `bug` — broken behavior, crash, mismatch, false negative, bad parsing, auth failure
|
||
- `enhancement` — feature request, UX improvement, support for a new workflow
|
||
- `documentation` — docs, onboarding, missing setup guidance
|
||
- `question` — only for issues that are primarily asking for clarification or support
|
||
|
||
Avoid using `question` as a generic fallback when the issue is actually a bug or feature request.
|
||
|
||
## Priority labels
|
||
|
||
- `priority:high` — crashes, install failures, auth/account breakage, provider unusable, severe resource issues
|
||
- `priority:medium` — real issue or good feature request, but not urgent
|
||
- `priority:low` — minor polish, optional UX improvements, long-tail backlog
|
||
|
||
## Workflow labels
|
||
|
||
- `needs-triage` — new issue that has not been categorized yet
|
||
- `needs-repro` — needs logs, screenshots, exact steps, or a current repro
|
||
- `needs-design` — valid request, but needs a product/UX decision before implementation
|
||
- `blocked-upstream` — likely caused or limited by upstream provider behavior
|
||
- `accepted` — intentionally kept open as part of the backlog/roadmap
|
||
|
||
## Area labels
|
||
|
||
- `area:auth-keychain` — keychain prompts, login state, token refresh, account switching
|
||
- `area:install-distribution` — Homebrew, packaging, launch/install failures, binary detection
|
||
- `area:usage-accuracy` — usage %, reset windows, plan parsing, cost/token math
|
||
- `area:performance` — CPU, battery, memory, background sessions/process churn
|
||
- `area:ui-ux` — menu bar behavior, settings, copy, visual layout, interaction polish
|
||
- `area:widget` — widget registration, app groups, widget gallery visibility
|
||
- `area:docs-onboarding` — setup docs, onboarding docs, missing instructions
|
||
- `area:notifications` — threshold alerts, prompt waiting, quota notifications
|
||
- `area:export-integration` — Prometheus, HTTP server mode, external integrations
|
||
- `area:accounts` — multiple accounts, account discovery, account switching UX
|
||
|
||
## Provider labels
|
||
|
||
Only apply one when a provider is clearly the main subject:
|
||
|
||
- `provider:claude`
|
||
- `provider:codex`
|
||
- `provider:cursor`
|
||
- `provider:copilot`
|
||
- `provider:gemini`
|
||
- `provider:alibaba`
|
||
- `provider:factory`
|
||
- `provider:antigravity`
|
||
- `provider:opencode`
|
||
- `provider:zai`
|
||
- `provider:openrouter`
|
||
|
||
Not every issue needs a provider label.
|
||
|
||
## Close-time labels
|
||
|
||
These are mostly useful when resolving issues, not as backlog-organizing labels:
|
||
|
||
- `duplicate`
|
||
- `invalid`
|
||
- `wontfix`
|
||
- `stale`
|
||
|
||
## Recommended minimum viable label set
|
||
|
||
If starting from a sparse tracker, add these first:
|
||
|
||
### Priority
|
||
- `priority:high`
|
||
- `priority:medium`
|
||
- `priority:low`
|
||
|
||
### Workflow
|
||
- `needs-triage`
|
||
- `needs-repro`
|
||
- `needs-design`
|
||
- `accepted`
|
||
|
||
### Area
|
||
- `area:auth-keychain`
|
||
- `area:install-distribution`
|
||
- `area:usage-accuracy`
|
||
- `area:performance`
|
||
- `area:ui-ux`
|
||
- `area:widget`
|
||
- `area:docs-onboarding`
|
||
|
||
### Provider
|
||
- `provider:claude`
|
||
- `provider:codex`
|
||
- `provider:cursor`
|
||
- `provider:copilot`
|
||
|
||
This smaller set already gives most of the value.
|
||
|
||
## Examples
|
||
|
||
### Example 1 — severe Claude keychain issue
|
||
Issue: repeated Claude keychain prompts, user can’t keep the app running normally.
|
||
|
||
Suggested labels:
|
||
- `bug`
|
||
- `priority:high`
|
||
- `area:auth-keychain`
|
||
- `provider:claude`
|
||
|
||
### Example 2 — roadmap feature
|
||
Issue: multiple account support.
|
||
|
||
Suggested labels:
|
||
- `enhancement`
|
||
- `priority:high`
|
||
- `area:accounts`
|
||
- `needs-design`
|
||
|
||
### Example 3 — needs better repro
|
||
Issue: generic usage mismatch with unclear screenshots and no exact values.
|
||
|
||
Suggested labels:
|
||
- `bug`
|
||
- `priority:medium`
|
||
- `area:usage-accuracy`
|
||
- `needs-repro`
|
||
|
||
### Example 4 — accepted backlog UI request
|
||
Issue: show burn rate / pacing indicators.
|
||
|
||
Suggested labels:
|
||
- `enhancement`
|
||
- `priority:medium`
|
||
- `area:usage-accuracy`
|
||
- `accepted`
|
||
|
||
## Suggested rollout
|
||
|
||
1. **Create the new labels**
|
||
2. **Backfill the top-priority open issues first**
|
||
- all `priority:high` bugs
|
||
- major roadmap items
|
||
- maintainer-triage issues
|
||
3. **Apply labels to new issues at intake**
|
||
4. **Backfill older backlog issues gradually**
|
||
|
||
## Practical guidance
|
||
|
||
- Prefer **fewer, clearer labels** over many vague labels.
|
||
- Do not label everything `question`.
|
||
- Do not use both `needs-repro` and `accepted` on the same issue unless there is a strong reason.
|
||
- If an issue is provider-specific, add the provider label early.
|
||
- If an issue is obviously real and intended to stay open, add `accepted` so it doesn’t look abandoned.
|
||
|
||
## Current workflow-specific labels
|
||
|
||
These already exist and should stay scoped to their current purpose:
|
||
|
||
- `upstream-sync`
|
||
- `needs-review`
|
||
- `changes requested`
|
||
|
||
They should not replace the general issue triage labels above.
|