Issue Labels

Issue Labels

This repository replaces GitHub's flat default labels with a grouped, prefixed label scheme. This page explains the design and how to use it.

Why not just the defaults?

GitHub creates bug, documentation, duplicate, enhancement, good first issue, help wanted, invalid, question, wontfix (and newer repos also accessibility). They mix three different questions in one flat list:

• what kind of work is this? (bug, enhancement)
• what is its state? (duplicate, wontfix)
• who can help? (help wanted)

…and say nothing about priority, size or which part of the project is affected.

Research summary

Source	Key idea adopted
GitHub Docs - Managing labels	Labels are repo-wide; good first issue and help wanted are recognised by GitHub and surfaced to new contributors → keep them unchanged.
Dave Lunny - Sane GitHub Labels	Use a Category: Value prefix so labels sort into groups; one colour family per group.
Robin - Best-practice system for organizing and tagging GitHub issues	Separate Type, Status and Priority; colour groups make a board readable at a glance.
Relequestual - sensible-github-labels	Workflow/status labels for teams that like structure.
IPFS - ISSUE_LABELS.md	Effort / difficulty labels help people pick suitable work.

Design rules

1. Prefix = group. Group: Value - alphabetical sorting then keeps each group together.
2. One colour family per group, so the colour tells you the group before you read the text.
3. Every label has a description (shown as a tooltip on GitHub).
4. Exactly one Type, one Priority, at most one Status per open issue. Effort and Area are optional but encouraged.
5. Rename, don't delete defaults - their meaning is preserved (e.g. enhancement → Type: Feature, wontfix → Status: Won't Fix).
6. Keep the list short (≈25). Too many labels = nobody uses them.

The labels

Type - what kind of work? (distinct, saturated colours)

Label	Colour	Use when…
Type: Bug	#d73a4a	something is broken or behaves unexpectedly
Type: Feature	#a2eeef	new functionality or an improvement
Type: Documentation	#0075ca	README, wiki or other docs
Type: Research	#006b75	we must investigate/learn before acting
Type: Question	#d876e3	information or a decision is needed
Type: Chore	#c5def5	housekeeping, no user-facing change

Priority - how urgent? (heat scale: red → green)

Label	Colour	Meaning
Priority: Critical	#b60205	blocks the project - fix now
Priority: High	#d93f0b	this cycle
Priority: Medium	#fbca04	soon
Priority: Low	#0e8a16	when time allows

Status - where in the workflow? (neutral / pastel)

Label	Colour	Meaning
Status: Needs Triage	#ededed	new, not yet reviewed
Status: In Progress	#c2e0c6	someone is working on it
Status: Needs Review	#fef2c0	done, waiting for feedback
Status: Blocked	#000000	waiting on something else (link it!)
Status: Duplicate	#cfd3d7	already tracked - link and close
Status: Invalid	#e4e669	not actionable
Status: Won't Fix	#ffffff	valid but out of scope - explain why

Effort - how big? (purple ramp, light → dark)

Label	Meaning
Effort: Small	< 1 hour
Effort: Medium	a few hours
Effort: Large	a day or more - consider splitting

Area - which part of the project? (warm browns)

Area: README · Area: Wiki · Area: Repo Setup · Area: Accessibility · Area: Design · Area: Backend · Area: Frontend · Area: Deployment (the last four were added for the term project)

Community (GitHub-recognised, unchanged names)

good first issue · help wanted

Lifecycle of an issue

 opened --► Status: Needs Triage --► (add Type + Priority + Effort + Area)
                                      │
                                      ▼
                              Status: In Progress --► Status: Needs Review --► closed
                                      │
                                      └--► Status: Blocked (link the blocker)

Handy filters

• All high-priority docs work: is:open label:"Type: Documentation" label:"Priority: High"
• Untriaged issues: is:open label:"Status: Needs Triage"
• Quick wins: is:open label:"Effort: Small"