Issue and pull request labels
TL;DR Five groups: work-type, outside-contribution, pull request size, scope and readiness, and triage. Work-type and pull request size are automatic. A pull request inherits
good first issuefrom a linked closing issue; the remaining labels are applied by hand.
The labels already exist on the repository with the colors below. This file is the record of what they mean and how each one gets applied, so the scheme does not drift as issues are filed.
Work-type
Exactly one per issue. Every issue form applies it automatically, so an issue opened through a form arrives already labeled.
| Label | Color | Meaning | Applied by |
|---|---|---|---|
bug | #d73a4a | Something isn't working | Bug report form |
enhancement | #a2eeef | New feature or request | Feature request form |
documentation | #0075ca | Improvements or additions to documentation | Documentation form |
refactor | #fbca04 | Code restructuring without behavior change | Maintenance: refactoring form |
test | #0e8a16 | Test coverage and fixtures | Maintenance: tests form |
chore | #bfd4f2 | Tooling, CI, and dependencies | Maintenance: tooling, CI, dependencies form |
The three kinds of maintenance are separate forms rather than one form with a type dropdown, so each carries its own work-type label and none needs a label applied by hand.
On a pull request the same label comes from the title, which already names the
type because titles follow Conventional Commits. .github/workflows/pr-label.yml
maps the commit types in CONTRIBUTING.md to the labels
above, keeps exactly one of them on the pull request so a corrected title does
not leave the old one behind, and fails when the title starts with something
that has no label, which is also the check that the title follows the format.
| Commit type | Label |
|---|---|
feat | enhancement |
fix | bug |
docs | documentation |
refactor | refactor |
test | test |
chore | chore |
Outside-contribution
Applied by hand to issues during triage, on top of a work-type label, to mark
work shaped for someone arriving from outside. A pull request inherits
good first issue when it closes an issue carrying that label. help wanted
stays on the issue.
| Label | Color | Meaning |
|---|---|---|
good first issue | #7057ff | Good for newcomers |
help wanted | #008672 | Extra attention is needed |
Pull request size
Exactly one per pull request and never applied to an issue. The PR label workflow adds additions and deletions, applies the matching black label, and replaces it when the diff changes.
| Label | Color | Changed lines |
|---|---|---|
📏 xs | #000000 | 0–9 |
📏 s | #000000 | 10–49 |
📏 m | #000000 | 50–199 |
📏 l | #000000 | 200–999 |
📏 xl | #000000 | 1,000 or more |
Scope and readiness
Applied by hand during triage, on top of a work-type label. Two of these say what
the work touches, and two say whether it can start. None of them can come from a
Conventional Commits prefix, which carries only the kind of change, so none of
them is applied by .github/workflows/pr-label.yml.
| Label | Color | Meaning |
|---|---|---|
fidelity | #c05621 | Answering it means observing real socket.io |
breaking | #7b341e | Major under decision 0019 |
needs decision | #ed8936 | A decision is needed before any code |
blocked | #fbd38d | Cannot start until another issue settles |
The four share one shade family so the group reads as a group next to the reds, blues and greens above. The shade within the family carries no meaning.
fidelity needs a boundary sharp enough to stop it spreading. Every delivery
change is checked against socket.io, so "was verified against socket.io" would
catch all of them and mark nothing. The line is whether observing socket.io is
the work, which holds when the issue cannot be answered from a decision taken
here and only real socket.io settles it.
breaking is the label for a change that
decision 0019 puts in the
major row. That is removing or altering a differences.md
§A entry, a public type change that stops existing call sites compiling, and
raising engines.node. A conformance correction is not one of these, however
much it moves, which is the point 0019 settles. Before 1.0.0 those changes ship
as minor, so the label marks what was touched rather than which number moved.
needs decision does not overlap with the Issues column in
decisions/README.md. That column is backward-looking,
listing the issues an existing decision record came out of. This label is
forward-looking, on an issue where no record exists yet.
Triage
Applied by hand to record how an issue was resolved. A question is normally
routed to Discussions by the issue-form configuration rather than filed as an
issue, so question is rare on the tracker.
| Label | Color | Meaning |
|---|---|---|
question | #d876e3 | Further information is requested |
duplicate | #cfd3d7 | This issue or pull request already exists |
invalid | #e4e669 | This doesn't seem right |
wontfix | #ffffff | This will not be worked on |