Skip to content

Document structured label usage #2010

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

Merged
yoshuawuyts merged 8 commits into from
Nov 12, 2026
+175 −78
Merged

Document structured label usage #2010

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d911577
Document structured label usage
yoshuawuyts Nov 2, 2026
443c073
Keep label guidance close to the existing structure
yoshuawuyts Nov 2, 2026
a7dc89d
Restore structured label guide to d31f2270
yoshuawuyts Nov 10, 2026
f84d29c
Align label guide tables
yoshuawuyts Nov 10, 2026
c7b73a6
Describe the merged HIP as the label scheme
yoshuawuyts Nov 10, 2026
43afcee
Clarify label guidance during migration
yoshuawuyts Nov 10, 2026
c6c9c5c
Describe structured labels throughout the usage guide
yoshuawuyts Nov 10, 2026
791c8b4
Use duplicate closure reason in label guidance
yoshuawuyts Nov 10, 2026
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
253 changes: 175 additions & 78 deletions docs/github-labels.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,82 +1,179 @@
# **Pull Requests (PRs)**
# GitHub labels

This guide describes the labeling scheme defined in
[HIP 0005](../proposals/0005-structured-labels/README.md).
The HIP covers rationale and migration.

## Choosing labels

Each prefix answers a different question. Combine labels to describe an issue
or PR. Area labels vary by project. Most other labels are shared across the org.

| Prefix | Meaning | Describes |
| ------ | ------------- | ------------------------------------------------- |
| `A-` | Area | The part of the project affected |
| `C-` | Category | The type of issue or change |
| `E-` | Participation | A good first issue or a request for help |
| `F-` | Feature | A feature or initiative being tracked |
| `O-` | Platform | CPU architecture, operating system, or hypervisor |
| `P-` | Priority | Urgency or release importance |
| `S-` | Status | Workflow state or outstanding action |

For example:

* An API bug fix gets `A-api` and `C-bug`.
* A documentation fix gets `A-docs` and `C-bug`. Documentation improvements get
`A-docs` and `C-enhancement`.
* An MSHV bug on Linux awaiting triage gets `O-mshv`, `O-linux`, `C-bug`, and
`S-needs-triage`.

## Categories

| Label | Use for |
| --------------- | -------------------------------------------------------------------------------------------------- |
| `C-bug` | Bug reports and fixes |
| `C-deps` | PRs that update dependencies or related components |
| `C-enhancement` | New features or backward-compatible improvements, including documentation and tests |
| `C-refactor` | Restructuring or removing code without adding functionality, including changes to user-facing APIs |
| `C-question` | Questions or requests for information |

The [PR label check](../.github/workflows/PRLabelChecker.yml) requires exactly one
change category before merging: `C-bug`, `C-deps`, `C-enhancement`, or
`C-refactor`. See the HIP's
[label conversion table](../proposals/0005-structured-labels/README.md#label-conversion)
for the mapping.

## Areas

Area labels are optional. Add those that help identify the affected parts of
the project.

| Label | Use for |
| -------------------------- | ------------------------------------------------------- |
| `A-api` | APIs and public interfaces |
| `A-ci` | CI workflows and GitHub Actions |
| `A-ci-periodics` | Failures from scheduled CI jobs |
| `A-ci-periodics-aarch64` | Daily aarch64 CI failures |
| `A-ci-periodics-mshv-6.18` | Weekly MSHV 6.18 CI failures |
| `A-ci-periodics-nightly` | Nightly Rust CI failures |
| `A-deps` | Dependencies or related components as the affected area |
| `A-docs` | Documentation |
| `A-fuzzing` | Fuzzing |
| `A-infra` | Infrastructure |
| `A-perf` | Performance |
| `A-security` | Security |
| `A-testing` | Tests and testing infrastructure |

`A-deps` identifies an area. `C-deps` identifies a dependency update. A dependency
update needs `C-deps`, with an area label only when it helps describe the change.

The [CI failure notifier](../dev/notify-ci-failure.sh) creates or updates an open
issue using the first supplied label as its grouping key. The
[daily aarch64](../.github/workflows/DailyArm64.yml),
[weekly MSHV 6.18](../.github/workflows/WeeklyMshv618.yml), and
[nightly Rust](../.github/workflows/RustNightly.yml) workflows each use a dedicated
key. This keeps their failures on separate release-blocking issues, even when
they also carry the general periodic-CI label.

## Participation and features

| Label | Use for |
| --------------- | ----------------------------------------------- |
| `E-easy` | Good first issues suitable for new contributors |
| `E-help-wanted` | Requests for help |
| `F-guest-cow` | Work on guest copy-on-write support |

`E-easy` is the only difficulty label in this scheme. There are no size labels.

## Platforms

Use platform labels when an item is specific to an architecture, host OS, or
hypervisor. Combine them where relevant.

| Label | Use for |
| ----------- | ---------------------------------------- |
| `O-x86_64` | x86-64 processors |
| `O-aarch64` | 64-bit Arm processors |
| `O-kvm` | Linux KVM backend |
| `O-mshv` | Linux MSHV backend for Microsoft Hyper-V |
| `O-whp` | Windows Hypervisor Platform backend |
| `O-hvf` | macOS Hypervisor Framework backend |
| `O-linux` | Linux host support |
| `O-windows` | Windows host support |
| `O-macos` | macOS host support |

## Status

Status labels are composable. For example, a PR can need review
and be nominated for discussion at the next meeting.

| Label | Use when |
| ---------------------- | ------------------------------------------------------------ |
| `S-needs-triage` | An item needs initial assessment |
| `S-needs-review` | A PR is ready for review or re-review |
| `S-waiting-on-author` | The author needs to provide information or make changes |
| `S-needs-repro` | A reproduction is needed to confirm a bug |
| `S-confirmed` | A bug is verified or an enhancement is considered reasonable |
| `S-blocked` | Another issue or external factor blocks progress |
| `S-nominated` | An item is nominated for discussion at the next meeting |
| `S-needs-announcement` | An item should be announced in the next release |
| `S-needs-goldens` | A PR needs snapshot golden regeneration |

`S-confirmed` does not promise implementation or a timeline.
`S-needs-repro` describes what is missing. Add
`S-waiting-on-author` when the author needs to supply it.

The [issue labeler](../.github/workflows/IssueLabelChecker.yml) preserves all
`S-` statuses. It adds `S-needs-triage` only when no status is present.
Remove that label after assessment.

### Review readiness

`S-needs-review` signals that a PR is awaiting review.
Add it when opening a review-ready PR, or after addressing requested changes and
re-requesting review.

The existing [`collect`](../.github/workflows/ready-for-review-label.yml) and
[`manage`](../.github/workflows/ready-for-review-manage.yml) workflows remove
`S-needs-review` automatically when any of these conditions apply:

* The PR is closed or merged.
* The PR is converted to a draft.
* The PR has two or more approvals.
* The PR has two or more change requests.

Only reviews of the current head commit count toward these thresholds.
Authors add the label. Automation handles removal.

### Snapshot goldens

`S-needs-goldens` requests regeneration for a PR that intentionally changes the
snapshot format and bumps `GOLDENS_VERSION`. The verify job generates goldens
from the branch and checks them with the branch loader. This allows verification
before the new golden set is published.

The [PR workflow](../.github/workflows/ValidatePullRequest.yml) checks
`S-needs-goldens` to select this mode. See
[snapshot versioning](snapshot-versioning.md) for the golden update process.

## Release priority

`P-release-blocker` marks issues that must be resolved before the next release.
Any open issue with the release-blocking label prevents release creation.
The [release check](../dev/check-release-blockers.sh) queries
`P-release-blocker`.

We use GitHub labels to categorize PRs. Before a PR can be merged, it must be assigned one of the following **kind/** labels:
## Issue types and closure

Issues also use GitHub issue types. These are separate from labels:

- **kind/bugfix** - For PRs that fix bugs.
- **kind/dependencies** - For PRs that update dependencies or related components.
- **kind/enhancement** - For PRs that introduce new features or improve existing functionality. This label also applies to improvements in documentation, testing, and similar areas. Any changes must be backward-compatible.
- **kind/refactor** - For PRs that restructure or remove code without adding new functionality. This label also applies to changes that affect user-facing APIs.
* **bug** reports an unexpected problem or incorrect behavior.
* **design** covers design considerations or decisions.
* **enhancement** suggests a feature, improvement, or idea.

## Review readiness
Use GitHub's closure reasons to record resolution:

We use the **ready-for-review** label to signal that a PR is waiting for a (re-)review:

- **Add** `ready-for-review` when you open a PR that is ready for review, or when a PR is ready for re-review (for example, once you have addressed requested changes and re-requested review).
- The label is **removed automatically** by the ready-for-review label automation (the [`collect`](../.github/workflows/ready-for-review-label.yml) and [`manage`](../.github/workflows/ready-for-review-manage.yml) workflows) once the PR is no longer awaiting that review, specifically when any of the following become true:
- the PR is closed or merged,
- the PR is converted to a draft,
- the PR has two or more approvals, or
- the PR has two or more change requests.

You only ever need to add the label; removal is fully automated.

---

# **Issues**

Issues are categorized using the following three **GitHub types** (not GitHub labels):

- **bug** - Reports an unexpected problem or incorrect behavior.
- **design** - Relates to design considerations or decisions.
- **enhancement** - Suggests a new feature, improvement, or idea.

To track the lifecycle of issues, we also use GitHub labels:

- **lifecycle/needs-review** - A temporary label indicating that the issue has not yet been reviewed.
- **lifecycle/confirmed** - Confirms the issue’s validity:
- If the issue type is **bug**, the bug has been verified.
- If the issue type is **enhancement**, the proposal is considered reasonable but does not guarantee implementation.
- This label does not indicate when or if the fix or enhancement will be implemented.
- **lifecycle/needs-info** - The issue requires additional information from the original poster (OP).
- **lifecycle/blocked** - The issue is blocked by another issue or external factor.

The following labels should be applied to issues prior to closing, indicating the resolution status of the issue:

- **lifecycle/duplicate** - The issue is a duplicate of another issue.
- **lifecycle/fixed** - The issue has been resolved.
- **lifecycle/not-a-bug** - The issue is not considered a bug, and no further action is needed.
- **lifecycle/wont-fix** - The issue will not be fixed.

In addition to lifecycle labels, we use the following labels to further categorize issues:

- **good-first-issue** - The issue is suitable for new contributors or those looking for a simple task to start with.
- **help-wanted** - The issue is a request for help or assistance.
- **question** - The issue is a question or request for information.
- **release-blocker** - Critical issues that must be resolved before the next release can be made. The presence of this label on any open issue will prevent releases being created by the release workflow

---

# **Issues & PRs**

In addition to **kind/*** labels, we use optional **area/*** labels to specify the focus of a PR or issue. These labels are purely for categorization, and are not mandatory.

- **area/API** - Related to the API or public interface.
- **area/ci-periodics** - Applied to issues that track failures from scheduled (periodic) CI jobs. These issues are opened automatically by the CI failure notifier (`dev/notify-ci-failure.sh`).
- **area/ci-periodics-aarch64** - De-duplication label for failures from the daily aarch64 workflow (`.github/workflows/DailyArm64.yml`). It keeps those failures on their own dedicated, release-blocking issue instead of sharing the general `area/ci-periodics` issue.
- **area/ci-periodics-mshv-6.18** - De-duplication label for failures from the weekly MSHV 6.18 workflow (`.github/workflows/WeeklyMshv618.yml`). It keeps those failures on their own release-blocking issue.
- **area/dependencies** - Concerns dependencies or related components. This label is different from **kind/dependencies**, which should only used for PRs.
- **area/documentation** - Related to documentation updates or improvements.
- **area/infrastructure** - Concerns infrastructure rather than core functionality.
- **area/performance** - Addresses performance.
- **area/security** - Involves security-related changes or fixes.
- **area/testing** - Related to tests or testing infrastructure.

## Workflow labels

Some labels change CI behaviour on a PR rather than categorizing it:

- **regen-goldens** - Switches the snapshot golden verify job into regenerate mode. A PR that intentionally changes the snapshot format and bumps `GOLDENS_VERSION` carries this label so the verify job generates the goldens from the branch and runs them back through the branch loader, rather than pulling a published tag set that does not exist yet. See [snapshot-versioning.md](snapshot-versioning.md).


## Notes
This document is a work in progress and may be updated as needed. The labels and categories are subject to change based on the evolving needs of the project and community feedback.
* Close resolved issues as **completed**.
* Close duplicate issues as **duplicate**, linking to the original issue.
* Explain findings that are not bugs and close them as **not planned**.
* Explain decisions not to pursue an issue and close it as **not planned**.
Loading