How we label and schedule issues and pull requests. The goal is that anyone can open the issue list, filter it, and see what to work on next and why.
Every open issue should have:
- one type (
bug,enhancement,refactor,maintenance,documentation); - one status (
status: …); - one priority (
priority: …), except trackers and umbrella issues; - at least one area (
area: …) when an area fits; - a milestone once it's scheduled.
Flags such as data-loss or good first issue are added only when they apply.
The label families use a family: value prefix, like status: blocked, so
they sort together in GitHub's label picker and read clearly in the issue
list. obsidian-tasks uses the same convention (scope: …, status: …,
priority: …).
| Label | Use for |
|---|---|
bug |
Something isn't working as intended |
enhancement |
A new feature, or a change to how an existing feature behaves |
refactor |
Behavior-preserving restructuring (see #436 and Refactors (#436) in AGENTS.md) |
maintenance |
Tooling, cleanup, compliance, and upkeep with no user-visible change |
documentation |
Documentation additions, corrections, and reorganization |
Dependabot applies dependencies, github_actions, and javascript to its
own pull requests. Leave them as they are.
Status tracks where an issue is in its lifecycle. Replace the previous status when it changes; don't stack them.
| Label | Meaning |
|---|---|
status: needs-triage |
New; a maintainer needs to review and label it |
status: needs-info |
Waiting on the reporter for more information |
status: accepted |
Confirmed and ready to work on |
status: blocked |
Waiting on another issue or decision; the issue body names it (for example "Blocked by #436") |
status: in-progress |
Someone is working on it |
status: ready-for-testing |
A fix is available and needs manual testing |
status: pending-release |
Merged; ships in the next release |
Closed issues don't need a status. Use duplicate or wontfix when an issue
is closed without a fix.
Priority says when we intend to deal with an issue.
| Label | Meaning |
|---|---|
priority: high |
Immediate attention: next up, ahead of planned work |
priority: medium |
Normal backlog item, scheduled into a milestone |
priority: low |
Minor fix or nice-to-have; done when convenient |
Trackers and umbrella issues (release trackers, #436) don't get a priority.
These describe how bad a problem is, separately from when we'll fix it. A
rare data-loss bug can be data-loss and still priority: medium.
| Label | Meaning |
|---|---|
data-loss |
Can lose or overwrite user data. These are the major fixes that may still target a frozen release branch (#436, phase 2); see Freezing the release branch in CONTRIBUTING.md |
regression |
Worked in an earlier release and is broken now. Name the last working version in the issue |
breaking change |
Changes behavior, stored data, or requirements (such as minAppVersion) in a way users must adapt to. Ships only in a major release, bundled with the other breaking changes in its milestone |
accessibility |
A barrier for keyboard, screen-reader, low-vision, or other assistive-technology users. Fix it the way the accessibility guidelines recommend, such as native elements before ARIA roles |
Area says which part of the plugin is affected. Use more than one when an issue spans parts.
| Label | Covers |
|---|---|
area: dashboard |
Dashboard view: article list, filters, selection |
area: sidebar |
Feed and folder sidebar, including the navigation drawer |
area: reader |
Reader view and article rendering |
area: refresh |
Fetching, parsing, and refreshing feeds |
area: import-export |
OPML, preferences, and bundle import and export |
area: storage |
Settings, shards, user state, and on-disk layout |
area: build |
Build, CI, release tooling, and minAppVersion |
| Label | Meaning |
|---|---|
good first issue |
Small and well scoped; a good place to start. GitHub surfaces these to new contributors |
help wanted |
Maintainers would welcome a contribution |
ready-for-agent |
Fully specified, ready for an AFK agent |
ready-for-human |
Fully specified, but needs a human to implement |
| Label | Meaning |
|---|---|
duplicate |
Another issue or pull request covers this; link it when closing |
wontfix |
Won't be worked on; explain why when closing |
wayfinder:map, wayfinder:research, wayfinder:grilling, wayfinder:task, wayfinder:prototype |
Wayfinder planning issues: a map and its prerequisite decisions and tasks |
| Milestone | Holds |
|---|---|
A release number, such as 2.7.0 or 2.8.0 |
Work planned to ship in that release |
3.0.0 |
The next major release: breaking changes bundled together (see breaking change) |
vNext |
Accepted work that isn't scheduled for a specific release yet |
Move an issue to a release milestone when it's scheduled, and out again if it slips. An unfixed issue in a closed release milestone should move to the next one.
When a new issue arrives:
- Confirm it's actionable. If not, apply
status: needs-infoand ask the reporter, or close it asduplicateorwontfixwith a reason. - Apply a type, an area, and a priority. Add
data-loss,regression, orbreaking changeif they apply. - Replace
status: needs-triagewithstatus: accepted, or withstatus: blockedplus a "Blocked by #…" line in the body. - Add a milestone once it's scheduled.
Labels track an issue through the Idea-to-Release Workflow in
README.md. Each stage changes them as
follows.
| Stage | Label and milestone changes |
|---|---|
| Issue opened | The bug and feature templates apply bug or enhancement plus status: needs-triage; the refactor template applies refactor |
| Triaged | Follow the triage checklist above: status: accepted (or blocked, needs-info, wontfix), plus a priority and an area |
| Scheduled | A release milestone, or vNext if it's accepted but not scheduled |
| Ready to pick up | Add ready-for-agent or ready-for-human once the issue is specified well enough to hand off |
| Work starts | status: in-progress, and an issue branch named per branch-naming.md |
| Fix needs manual checks | status: ready-for-testing while a pull request waits on a fixture-vault or beta checklist |
| Merged | A pull request that says Fixes #… closes the issue on merge to dev (the default branch). Closed issues don't need a status. Use status: pending-release only for an issue that stays open until a release, for example a fix on a release branch |
Contributors choose their own tools, and nothing here is required. The
maintainers use Matt Pocock's skills,
plus local variants of some of them (grill, to-issue). Each step in that
flow keeps the labels above:
grill-with-docsandto-specto settle an idea, thento-ticketsto turn the spec into issues (status: accepted, plusready-for-agentorready-for-human).triagefor issues that arrive from outside (status: needs-triageto a decision).implementon an issue branch (status: in-progress), thencode-reviewbefore the pull request.wayfindermaps for larger, multi-issue efforts (wayfinder:labels).
Whatever tools you use, apply the same label changes at each stage.
The agent skills we use come from Matt Pocock's
skills. They refer to five canonical
triage roles: needs-triage, needs-info, ready-for-agent,
ready-for-human, and wontfix. docs/agents/triage-labels.md maps those
roles to our labels.
In that system an issue carries exactly one state role. Here,
status: needs-triage and status: needs-info are status labels, while
ready-for-agent and ready-for-human are flags on an issue that is
status: accepted: they say who can pick it up. The wayfinder: labels come
from the same skills.
- GitHub Docs, Managing labels:
the default labels (
bug,enhancement,documentation,duplicate,good first issue,help wanted,invalid,question,wontfix,accessibility) that this system keeps and extends. - GitHub Docs, Encouraging helpful contributions to your project with labels:
why
good first issuematters: GitHub uses it to surface approachable issues to new contributors. - Matt Pocock's skills, triage
and wayfinder:
the canonical triage roles and their state machine, and the
wayfinder:ticket labels. - obsidian-tasks labels:
prefixed families (
scope: …,status: …,priority: …) in a large Obsidian plugin. - obsidian-linter labels:
breaking-change,needs-triage,maintenance, and the GitHub defaults. - Dataview labels
and Obsidian Git labels:
priority levels, and area labels (for example
mobile,desktop) alongsidebug,good first issue,help wanted, andwontfix.