From d911577580b384c2a943329a04a838c26908db71 Mon Sep 17 00:00:00 2001 From: Yosh Date: Mon, 2 Nov 2026 11:57:42 +0100 Subject: [PATCH 1/8] Document structured label usage Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Signed-off-by: Yosh --- docs/github-labels.md | 261 +++++++++++++++++++++++++++++------------- 1 file changed, 179 insertions(+), 82 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 9dfe8a8e1..8729c5492 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -1,82 +1,179 @@ -# **Pull Requests (PRs)** - -We use GitHub labels to categorize PRs. Before a PR can be merged, it must be assigned one of the following **kind/** 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. - -## Review readiness - -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. +# GitHub labels + +This guide describes the proposed scheme in +[HIP 0005](../proposals/0005-structured-labels/README.md). +The HIP covers rationale and migration. Existing automation still uses legacy +names. Label renames and automation updates need a coordinated rollout. +Until then, use the names required by the current workflows. + +## 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 | + +Before merging a PR, assign one change category: `C-bug`, `C-deps`, +`C-enhancement`, or `C-refactor`. During migration, the +[PR label check](../.github/workflows/PRLabelChecker.yml) requires exactly one +`kind/*` label. + +## 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. These workflows still use +`area/ci-periodics*` names. + +## 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. Requests for author information documented under +`lifecycle/needs-info` use `S-waiting-on-author`. + +### Review readiness + +Add `S-needs-review` 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 +`ready-for-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. The rollout must preserve +these rules for `S-needs-review`. Until the workflows are migrated, add +`ready-for-review` to use this automation. + +### 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) still checks +`regen-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) still queries +`release-blocker` until migration. + +## Issue types and closure + +Issues also use GitHub issue types. These are separate from labels: + +* **bug** reports an unexpected problem or incorrect behavior. +* **design** covers design considerations or decisions. +* **enhancement** suggests a feature, improvement, or idea. + +Use GitHub's closure reasons to record resolution: + +* Close resolved issues as **completed**. +* Link duplicates to the original issue and close them as **not planned**. +* 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**. From 443c0731cbbef91e8e456eedcac7432999e6faff Mon Sep 17 00:00:00 2001 From: Yosh Date: Mon, 2 Nov 2026 12:00:55 +0100 Subject: [PATCH 2/8] Keep label guidance close to the existing structure Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 265 +++++++++++++++--------------------------- 1 file changed, 92 insertions(+), 173 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 8729c5492..724876ee7 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -1,179 +1,98 @@ -# GitHub labels - -This guide describes the proposed scheme in -[HIP 0005](../proposals/0005-structured-labels/README.md). -The HIP covers rationale and migration. Existing automation still uses legacy -names. Label renames and automation updates need a coordinated rollout. -Until then, use the names required by the current workflows. - -## 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 | - -Before merging a PR, assign one change category: `C-bug`, `C-deps`, -`C-enhancement`, or `C-refactor`. During migration, the -[PR label check](../.github/workflows/PRLabelChecker.yml) requires exactly one -`kind/*` label. - -## 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. These workflows still use -`area/ci-periodics*` names. - -## 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. Requests for author information documented under -`lifecycle/needs-info` use `S-waiting-on-author`. - -### Review readiness - -Add `S-needs-review` 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 -`ready-for-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. The rollout must preserve -these rules for `S-needs-review`. Until the workflows are migrated, add -`ready-for-review` to use this automation. - -### 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) still checks -`regen-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) still queries -`release-blocker` until migration. +# **Pull Requests (PRs)** -## Issue types and closure +This guide describes the proposed scheme in [HIP 0005](../proposals/0005-structured-labels/README.md). Existing automation still uses legacy names. Keep using those names until labels and automation are migrated together. -Issues also use GitHub issue types. These are separate from labels: +We use GitHub labels to categorize PRs. Before a PR can be merged, it must be assigned one of the following **C-** labels: -* **bug** reports an unexpected problem or incorrect behavior. -* **design** covers design considerations or decisions. -* **enhancement** suggests a feature, improvement, or idea. +* **C-bug**: For PRs that fix bugs. +* **C-deps**: For PRs that update dependencies or related components. +* **C-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. +* **C-refactor**: For PRs that restructure or remove code without adding new functionality. This label also applies to changes that affect user-facing APIs. -Use GitHub's closure reasons to record resolution: +The [PR label check](../.github/workflows/PRLabelChecker.yml) still requires exactly one `kind/*` label until migration. +## Review readiness + +We use the **S-needs-review** label to signal that a PR is waiting for a (re-)review: + +* **Add** `S-needs-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 review automation (the [`collect`](../.github/workflows/ready-for-review-label.yml) and [`manage`](../.github/workflows/ready-for-review-manage.yml) workflows) must preserve automatic removal 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. + +Only reviews of the current head commit count. Authors add the label, and automation handles removal. Until migration, this automation requires `ready-for-review`. + +--- + +# **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 status of issues, we also use GitHub labels: + +* **S-needs-triage**: A temporary label indicating that the issue has not yet been assessed. +* **S-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. +* **S-waiting-on-author**: The author needs to provide information or make changes. This includes requests previously labeled `lifecycle/needs-info`. +* **S-needs-repro**: A reproduction is needed to confirm a bug. +* **S-blocked**: The issue is blocked by another issue or external factor. + +Use GitHub's closure reasons to indicate resolution: + +* Link duplicate issues to the original and close as **not planned**. * Close resolved issues as **completed**. -* Link duplicates to the original issue and close them as **not planned**. -* 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**. +* Explain findings that are not bugs and close as **not planned**. +* Explain decisions not to fix an issue and close as **not planned**. + +In addition to status labels, we use the following labels to further categorize issues: + +* **E-easy**: The issue is suitable for new contributors or those looking for a simple task to start with. +* **E-help-wanted**: The issue is a request for help or assistance. +* **C-question**: The issue is a question or request for information. +* **P-release-blocker**: Critical issues that must be resolved before the next release can be made. Any open issue with the release-blocking label prevents release creation. The [release check](../dev/check-release-blockers.sh) still queries `release-blocker` until migration. + +--- + +# **Issues & PRs** + +Labels use seven prefixes: **A-** for area, **C-** for category, **E-** for participation, **F-** for feature, **O-** for platform, **P-** for priority, and **S-** for status. Area labels vary by project. Most other labels are shared across the org. + +In addition to **C-** labels, we use optional **A-** labels to specify the focus of a PR or issue. These labels are purely for categorization, and are not mandatory. + +* **A-api**: Related to the API or public interface. +* **A-ci**: Related to CI workflows and GitHub Actions. +* **A-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`). +* **A-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. +* **A-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. +* **A-ci-periodics-nightly**: De-duplication label for failures from the nightly Rust workflow (`.github/workflows/RustNightly.yml`). It keeps those failures on their own release-blocking issue. +* **A-deps**: Concerns dependencies or related components. This identifies the affected area. **C-deps** identifies a dependency update PR. +* **A-docs**: Related to documentation updates or improvements. Use with **C-bug** for fixes or **C-enhancement** for improvements. +* **A-fuzzing**: Related to fuzzing. +* **A-infra**: Concerns infrastructure rather than core functionality. +* **A-perf**: Addresses performance. +* **A-security**: Involves security-related changes or fixes. +* **A-testing**: Related to tests or testing infrastructure. + +The CI failure notifier still uses `area/ci-periodics*` names until migration. + +Platform labels identify architectures (**O-x86_64**, **O-aarch64**), host operating systems (**O-linux**, **O-windows**, **O-macos**), and hypervisor backends (**O-kvm**, **O-mshv**, **O-whp**, **O-hvf**). Combine them where relevant. **F-guest-cow** tracks guest copy-on-write support. + +## Workflow labels + +Status labels can be combined. For example, a PR can have both **S-needs-review** and **S-nominated**. + +* **S-nominated**: Nominated for discussion in the next meeting. +* **S-needs-announcement**: To announce in the next release. +* **S-needs-goldens**: Requests snapshot golden regeneration. 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. This allows verification before the new golden set is published. The [PR workflow](../.github/workflows/ValidatePullRequest.yml) still requires `regen-goldens` for this mode until migration. See [snapshot-versioning.md](snapshot-versioning.md). + +## Notes + +The scheme has no size labels or difficulty scale beyond **E-easy**. The labels and categories are subject to change based on the evolving needs of the project and community feedback. From a7dc89d3a0559b3ea63423674d25e466203cdd5a Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 12:59:08 +0100 Subject: [PATCH 3/8] Restore structured label guide to d31f2270 Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 265 +++++++++++++++++++++++++++--------------- 1 file changed, 173 insertions(+), 92 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 724876ee7..8729c5492 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -1,98 +1,179 @@ -# **Pull Requests (PRs)** +# GitHub labels + +This guide describes the proposed scheme in +[HIP 0005](../proposals/0005-structured-labels/README.md). +The HIP covers rationale and migration. Existing automation still uses legacy +names. Label renames and automation updates need a coordinated rollout. +Until then, use the names required by the current workflows. + +## 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 | + +Before merging a PR, assign one change category: `C-bug`, `C-deps`, +`C-enhancement`, or `C-refactor`. During migration, the +[PR label check](../.github/workflows/PRLabelChecker.yml) requires exactly one +`kind/*` label. + +## 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. These workflows still use +`area/ci-periodics*` names. + +## 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. Requests for author information documented under +`lifecycle/needs-info` use `S-waiting-on-author`. + +### Review readiness + +Add `S-needs-review` 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 +`ready-for-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. The rollout must preserve +these rules for `S-needs-review`. Until the workflows are migrated, add +`ready-for-review` to use this automation. + +### 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) still checks +`regen-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) still queries +`release-blocker` until migration. -This guide describes the proposed scheme in [HIP 0005](../proposals/0005-structured-labels/README.md). Existing automation still uses legacy names. Keep using those names until labels and automation are migrated together. +## Issue types and closure -We use GitHub labels to categorize PRs. Before a PR can be merged, it must be assigned one of the following **C-** labels: +Issues also use GitHub issue types. These are separate from labels: -* **C-bug**: For PRs that fix bugs. -* **C-deps**: For PRs that update dependencies or related components. -* **C-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. -* **C-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. -The [PR label check](../.github/workflows/PRLabelChecker.yml) still requires exactly one `kind/*` label until migration. +Use GitHub's closure reasons to record resolution: -## Review readiness - -We use the **S-needs-review** label to signal that a PR is waiting for a (re-)review: - -* **Add** `S-needs-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 review automation (the [`collect`](../.github/workflows/ready-for-review-label.yml) and [`manage`](../.github/workflows/ready-for-review-manage.yml) workflows) must preserve automatic removal 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. - -Only reviews of the current head commit count. Authors add the label, and automation handles removal. Until migration, this automation requires `ready-for-review`. - ---- - -# **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 status of issues, we also use GitHub labels: - -* **S-needs-triage**: A temporary label indicating that the issue has not yet been assessed. -* **S-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. -* **S-waiting-on-author**: The author needs to provide information or make changes. This includes requests previously labeled `lifecycle/needs-info`. -* **S-needs-repro**: A reproduction is needed to confirm a bug. -* **S-blocked**: The issue is blocked by another issue or external factor. - -Use GitHub's closure reasons to indicate resolution: - -* Link duplicate issues to the original and close as **not planned**. * Close resolved issues as **completed**. -* Explain findings that are not bugs and close as **not planned**. -* Explain decisions not to fix an issue and close as **not planned**. - -In addition to status labels, we use the following labels to further categorize issues: - -* **E-easy**: The issue is suitable for new contributors or those looking for a simple task to start with. -* **E-help-wanted**: The issue is a request for help or assistance. -* **C-question**: The issue is a question or request for information. -* **P-release-blocker**: Critical issues that must be resolved before the next release can be made. Any open issue with the release-blocking label prevents release creation. The [release check](../dev/check-release-blockers.sh) still queries `release-blocker` until migration. - ---- - -# **Issues & PRs** - -Labels use seven prefixes: **A-** for area, **C-** for category, **E-** for participation, **F-** for feature, **O-** for platform, **P-** for priority, and **S-** for status. Area labels vary by project. Most other labels are shared across the org. - -In addition to **C-** labels, we use optional **A-** labels to specify the focus of a PR or issue. These labels are purely for categorization, and are not mandatory. - -* **A-api**: Related to the API or public interface. -* **A-ci**: Related to CI workflows and GitHub Actions. -* **A-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`). -* **A-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. -* **A-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. -* **A-ci-periodics-nightly**: De-duplication label for failures from the nightly Rust workflow (`.github/workflows/RustNightly.yml`). It keeps those failures on their own release-blocking issue. -* **A-deps**: Concerns dependencies or related components. This identifies the affected area. **C-deps** identifies a dependency update PR. -* **A-docs**: Related to documentation updates or improvements. Use with **C-bug** for fixes or **C-enhancement** for improvements. -* **A-fuzzing**: Related to fuzzing. -* **A-infra**: Concerns infrastructure rather than core functionality. -* **A-perf**: Addresses performance. -* **A-security**: Involves security-related changes or fixes. -* **A-testing**: Related to tests or testing infrastructure. - -The CI failure notifier still uses `area/ci-periodics*` names until migration. - -Platform labels identify architectures (**O-x86_64**, **O-aarch64**), host operating systems (**O-linux**, **O-windows**, **O-macos**), and hypervisor backends (**O-kvm**, **O-mshv**, **O-whp**, **O-hvf**). Combine them where relevant. **F-guest-cow** tracks guest copy-on-write support. - -## Workflow labels - -Status labels can be combined. For example, a PR can have both **S-needs-review** and **S-nominated**. - -* **S-nominated**: Nominated for discussion in the next meeting. -* **S-needs-announcement**: To announce in the next release. -* **S-needs-goldens**: Requests snapshot golden regeneration. 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. This allows verification before the new golden set is published. The [PR workflow](../.github/workflows/ValidatePullRequest.yml) still requires `regen-goldens` for this mode until migration. See [snapshot-versioning.md](snapshot-versioning.md). - -## Notes - -The scheme has no size labels or difficulty scale beyond **E-easy**. The labels and categories are subject to change based on the evolving needs of the project and community feedback. +* Link duplicates to the original issue and close them as **not planned**. +* 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**. From f84d29cc50d9125e71ac681a739b71fd6e9992a1 Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 13:00:34 +0100 Subject: [PATCH 4/8] Align label guide tables Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 116 +++++++++++++++++++++--------------------- 1 file changed, 58 insertions(+), 58 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 8729c5492..1f25de4f6 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -11,15 +11,15 @@ Until then, use the names required by the current workflows. 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 | +| 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: @@ -31,13 +31,13 @@ For example: ## 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 | +| 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 | Before merging a PR, assign one change category: `C-bug`, `C-deps`, `C-enhancement`, or `C-refactor`. During migration, the @@ -49,21 +49,21 @@ Before merging a PR, assign one change category: `C-bug`, `C-deps`, 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 | +| 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. @@ -79,11 +79,11 @@ they also carry the general periodic-CI label. These workflows still use ## 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 | +| 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. @@ -92,34 +92,34 @@ they also carry the general periodic-CI label. These workflows still use 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 | +| 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 | +| 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 From c7b73a66dd07e1095f39d7c606fe32e9e17168a7 Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 13:01:47 +0100 Subject: [PATCH 5/8] Describe the merged HIP as the label scheme Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 1f25de4f6..40c1fc91d 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -1,6 +1,6 @@ # GitHub labels -This guide describes the proposed scheme in +This guide describes the labeling scheme defined in [HIP 0005](../proposals/0005-structured-labels/README.md). The HIP covers rationale and migration. Existing automation still uses legacy names. Label renames and automation updates need a coordinated rollout. From 43afcee54c10e4bd48c8480b0aef758d5622430a Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 13:03:10 +0100 Subject: [PATCH 6/8] Clarify label guidance during migration Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 37 ++++++++++++++++++++++++------------- 1 file changed, 24 insertions(+), 13 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 40c1fc91d..08c072f7c 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -39,10 +39,13 @@ For example: | `C-refactor` | Restructuring or removing code without adding functionality, including changes to user-facing APIs | | `C-question` | Questions or requests for information | -Before merging a PR, assign one change category: `C-bug`, `C-deps`, -`C-enhancement`, or `C-refactor`. During migration, the -[PR label check](../.github/workflows/PRLabelChecker.yml) requires exactly one -`kind/*` label. +Until migration, the [PR label check](../.github/workflows/PRLabelChecker.yml) +requires exactly one current category: `kind/bugfix`, `kind/dependencies`, +`kind/documentation`, `kind/enhancement`, or `kind/refactor`. +After migration, assign 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 @@ -106,8 +109,8 @@ hypervisor. Combine them where relevant. ## Status -Status labels are composable. For example, a PR can need review and be nominated -for discussion at the next meeting. +After migration, status labels are composable. For example, a PR can need review +and be nominated for discussion at the next meeting. | Label | Use when | | ---------------------- | ------------------------------------------------------------ | @@ -122,14 +125,23 @@ for discussion at the next meeting. | `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. Requests for author information documented under -`lifecycle/needs-info` use `S-waiting-on-author`. +`S-needs-repro` describes what is missing. After migration, add +`S-waiting-on-author` when the author needs to supply it. + +Until migration, use `lifecycle/needs-review` for initial assessment, +`lifecycle/confirmed` for confirmed issues, `lifecycle/blocked-on-author` for +author input, and `lifecycle/blocked` for external blockers. +The [issue labeler](../.github/workflows/IssueLabelChecker.yml) assigns +`lifecycle/needs-review` when a new issue lacks exactly one lifecycle label. +Remove it after assessment. After migration, remove `S-needs-triage` at the +same point. Requests for author information documented under +`lifecycle/needs-info` also map to `S-waiting-on-author`. ### Review readiness -Add `S-needs-review` when opening a review-ready PR, or after addressing requested -changes and re-requesting review. +Until migration, `ready-for-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. After migration, use `S-needs-review` for this purpose. The existing [`collect`](../.github/workflows/ready-for-review-label.yml) and [`manage`](../.github/workflows/ready-for-review-manage.yml) workflows remove @@ -142,8 +154,7 @@ The existing [`collect`](../.github/workflows/ready-for-review-label.yml) and Only reviews of the current head commit count toward these thresholds. Authors add the label. Automation handles removal. The rollout must preserve -these rules for `S-needs-review`. Until the workflows are migrated, add -`ready-for-review` to use this automation. +these rules for `S-needs-review`. ### Snapshot goldens From c6c9c5c9f498df6c436b4d5352530755f2ab5dfd Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 14:21:01 +0100 Subject: [PATCH 7/8] Describe structured labels throughout the usage guide Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 47 +++++++++++++++++-------------------------- 1 file changed, 18 insertions(+), 29 deletions(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 08c072f7c..6df31de02 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -2,9 +2,7 @@ This guide describes the labeling scheme defined in [HIP 0005](../proposals/0005-structured-labels/README.md). -The HIP covers rationale and migration. Existing automation still uses legacy -names. Label renames and automation updates need a coordinated rollout. -Until then, use the names required by the current workflows. +The HIP covers rationale and migration. ## Choosing labels @@ -39,11 +37,9 @@ For example: | `C-refactor` | Restructuring or removing code without adding functionality, including changes to user-facing APIs | | `C-question` | Questions or requests for information | -Until migration, the [PR label check](../.github/workflows/PRLabelChecker.yml) -requires exactly one current category: `kind/bugfix`, `kind/dependencies`, -`kind/documentation`, `kind/enhancement`, or `kind/refactor`. -After migration, assign one change category before merging: `C-bug`, `C-deps`, -`C-enhancement`, or `C-refactor`. See the HIP's +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. @@ -77,8 +73,7 @@ issue using the first supplied label as its grouping key. The [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. These workflows still use -`area/ci-periodics*` names. +they also carry the general periodic-CI label. ## Participation and features @@ -109,7 +104,7 @@ hypervisor. Combine them where relevant. ## Status -After migration, status labels are composable. For example, a PR can need review +Status labels are composable. For example, a PR can need review and be nominated for discussion at the next meeting. | Label | Use when | @@ -125,27 +120,22 @@ and be nominated for discussion at the next meeting. | `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. After migration, add +`S-needs-repro` describes what is missing. Add `S-waiting-on-author` when the author needs to supply it. -Until migration, use `lifecycle/needs-review` for initial assessment, -`lifecycle/confirmed` for confirmed issues, `lifecycle/blocked-on-author` for -author input, and `lifecycle/blocked` for external blockers. -The [issue labeler](../.github/workflows/IssueLabelChecker.yml) assigns -`lifecycle/needs-review` when a new issue lacks exactly one lifecycle label. -Remove it after assessment. After migration, remove `S-needs-triage` at the -same point. Requests for author information documented under -`lifecycle/needs-info` also map to `S-waiting-on-author`. +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 -Until migration, `ready-for-review` signals that a PR is awaiting review. +`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. After migration, use `S-needs-review` for this purpose. +re-requesting review. The existing [`collect`](../.github/workflows/ready-for-review-label.yml) and [`manage`](../.github/workflows/ready-for-review-manage.yml) workflows remove -`ready-for-review` automatically when any of these conditions apply: +`S-needs-review` automatically when any of these conditions apply: * The PR is closed or merged. * The PR is converted to a draft. @@ -153,8 +143,7 @@ The existing [`collect`](../.github/workflows/ready-for-review-label.yml) and * 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. The rollout must preserve -these rules for `S-needs-review`. +Authors add the label. Automation handles removal. ### Snapshot goldens @@ -163,16 +152,16 @@ 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) still checks -`regen-goldens` to select this mode. See +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) still queries -`release-blocker` until migration. +The [release check](../dev/check-release-blockers.sh) queries +`P-release-blocker`. ## Issue types and closure From 791c8b4febd032c5afa2b3f024f98e733b24adab Mon Sep 17 00:00:00 2001 From: Yosh Date: Tue, 10 Nov 2026 18:06:37 +0100 Subject: [PATCH 8/8] Use duplicate closure reason in label guidance Signed-off-by: Yosh Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/github-labels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/github-labels.md b/docs/github-labels.md index 6df31de02..36e09c14a 100644 --- a/docs/github-labels.md +++ b/docs/github-labels.md @@ -174,6 +174,6 @@ Issues also use GitHub issue types. These are separate from labels: Use GitHub's closure reasons to record resolution: * Close resolved issues as **completed**. -* Link duplicates to the original issue and close them as **not planned**. +* 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**.