From 596605be0bc5bd06e8bdf541919e0201b2568f6f Mon Sep 17 00:00:00 2001 From: Yosh Date: Fri, 23 Oct 2026 12:47:30 +0200 Subject: [PATCH 1/4] Add HIP 0005 - Structured Labels Signed-off-by: Yosh --- proposals/0005-structured-labels/README.md | 175 +++++++++++++++++++++ 1 file changed, 175 insertions(+) create mode 100644 proposals/0005-structured-labels/README.md diff --git a/proposals/0005-structured-labels/README.md b/proposals/0005-structured-labels/README.md new file mode 100644 index 000000000..afa755c00 --- /dev/null +++ b/proposals/0005-structured-labels/README.md @@ -0,0 +1,175 @@ +# HIP 0005 - Structured labels + +## Elevator pitch + +We propose a standard labeling scheme for issues and PRs on GitHub, largely +modeled after Rust’s labeling system. This will make it easier to plan meetings, +raise items for discussion, as well as make it easier to switch between +repositories. + +## Status quo + +Hyperlight currently uses different labeling schemes across projects. Despite +our best efforts, even the main Hyperlight project contains duplicate labels and +labels that don’t follow its primary labeling scheme. Although Hyperlight does +not use a monorepo, we still plan and coordinate development across all +repositories. Without a shared labeling vocabulary, it’s harder to coordinate +processes like triage and issue nomination. + +Currently the main Hyperlight project uses the following labels prefixes: + +- `area/` +- `kind/` +- `lifecycle/` +- `size/` + +In addition to these, there are 10 labels that don’t follow a framework, as well +as three pairs of seemingly duplicate labels. + +## What we propose to do about it + +I’m proposing three changes to issue labels: + +- All labels must fit within a structured labeling framework +- All repositories must follow this framework +- All labels should start with single-letter prefixes + +Under the proposed scheme, `lifecycle/blocked-on-author` would be renamed to +`S-waiting-on-author` (“status: waiting on author”). For a full overview of all +labels and their proposed names, see the section on implementation details. + +## Shiny future + +One of the most impressive things about how the Rust language team is run is its +ability to prioritize work and get back to people quickly. We want Hyperlight to +be used more, which means the project needs to be trusted—and that people need +to trust us and our processes. The Rust language team used to have a problem +with responsiveness, but it turned that around by improving its processes. For +at least the past year, it feels like nothing pressing has gotten stuck in +limbo. + +That’s not to say Hyperlight is doing poorly, but we could do better. In +particular, it would be nice if creating triage agendas and prioritizing work +items were easier. That requires organizing the existing work more effectively. +Since we do not have a monorepo, it also means creating consistency across +repositories. + +I’d love it if generating the agenda for the weekly meetings were as simple as +running a script to see which issues have been nominated, whether any items have +been filed specifically for the agenda, and whether any items need attention. + +## Implementation details and plan + +### Categories + +- **`A-` — Area:** The part of the project affected. +- **`C-` — Category:** The type of issue or change. +- **`E-` — Participation:** Difficulty, experience required, or requests for help. +- **`F-` — Feature:** A specific feature or initiative being tracked. +- **`O-` — Platform:** CPU architecture, operating system, and hypervisor. +- **`P-` — Priority:** Urgency or release importance. +- **`S-` — Status:** Workflow state, resolution, or outstanding action. + +### Label conversion + +| Label | Proposed replacement | +| ----------------------------- | -------------------------- | +| `area/API` | `A-api` | +| `area/ci-periodics` | `A-ci-periodics` | +| `area/ci-periodics-aarch64` | `A-ci-periodics-aarch64` | +| `area/ci-periodics-mshv-6.18` | `A-ci-periodics-mshv-6.18` | +| `area/ci-periodics-nightly` | `A-ci-periodics-nightly` | +| `area/dependencies` | `A-deps` | +| `area/documentation` | `A-docs` | +| `area/fuzzing` | `A-fuzzing` | +| `area/infrastructure` | `A-infra` | +| `area/performance` | `A-perf` | +| `area/security` | `A-security` | +| `area/testing` | `A-testing` | +| `github_actions` | `A-ci` | +| `good first issue` | `E-easy` | +| `Guest-COW` | `F-guest-cow` | +| `help-wanted` | `E-help-wanted` | +| `kind/bugfix` | `C-bug` | +| `kind/dependencies` | `C-deps` | +| `kind/documentation` | `C-docs` | +| `kind/enhancement` | `C-enhancement` | +| `kind/refactor` | `C-refactor` | +| `lifecycle/blocked` | `S-blocked` | +| `lifecycle/blocked-on-author` | `S-waiting-on-author` | +| `lifecycle/confirmed` | `S-confirmed` | +| `lifecycle/duplicate` | (1) | +| `lifecycle/fixed` | `S-fixed` | +| `lifecycle/needs-review` | `S-needs-triage` | +| `lifecycle/not-a-bug` | (2) | +| `lifecycle/wont-fix` | (3) | +| `question` | `C-question` | +| `ready-for-review` | `S-waiting-on-review` | +| `regen-goldens` | `S-needs-golden-regen` | +| `release-blocker` | `P-release-blocker` | +| `size/l` | `E-hard` | +| `size/m` | `E-medium` | +| `size/s` | `E-easy` | +| `size/xl` | `E-hard` | +| `size/xs` | `E-easy` | + +- 1: Link issue and close as not planned +- 2: Explain the finding and close as not planned +- 3: Close as not planned + +## New labels + +| Proposed label | Description | +| --------------- | -------------------------------------------- | +| `O-x86_64` | Specific to x86-64 processors | +| `O-aarch64` | Specific to 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 | +| `S-to-announce` | To announce in the next release | +| `S-needs-repro` | Needs a repro to confirm the bug | +| `S-nominated` | Nominated for discussion in the next meeting | + +## Frequently asked questions + +### Why use single-letter prefixes? + +I think this is a bit of a [Stroustrup’s +rule](https://buttondown.com/hillelwayne/archive/stroustrups-rule/): new +features want loud, explicit notation - established features want a terse +notation. A labeling system is not a programming language, but it’s still a +system we interact with. Short, terse labels are nice when we use something a +lot - and I plan for us to use this a lot. + +### Can an issue have multiple labels? + +Yes! In fact, they almost always should! For example, a bug about MSHV support +on Linux should be tagged `O-mshv`, `O-linux`, `C-bug`, and +`S-waiting-on-triage`. + +### This seems complicated, do we really need it? + +There are two kinds of systems: ones which we design, and once which are accrue +over time. Most of what we’re proposing in this HIP is an iteration on things +we’re already tracking, very little is completely new. All this HIP really does +is spell out the system in whole. + +### Can we automate parts of this? + +In the Rust project, Rustbot automatically tags issues with +`S-waiting-on-review` and `S-waiting-on-author` depending on who has last +responded. This makes it easier to e.g. scan for items which are blocked on us +and we should get back to. + +There is also the `S-needs-triage` label we’re proposing, which could be +automatically added whenever a new item is created. This would be easy to pick +up for agendas to discuss as part of triage. + +### Why is “participation” labeled with “E-” + +“Priority” is labeled “P-”, meaning participation needs a different prefix. Rust +uses “E-” which seems as good as any other. From a285fa5dd64507914ffa993e25f7805f1fe623f9 Mon Sep 17 00:00:00 2001 From: Yosh <2467194+yoshuawuyts@users.noreply.github.com> Date: Fri, 23 Oct 2026 12:56:48 +0200 Subject: [PATCH 2/4] Enhance README with rollout plan and label updates Add rollout plan for label migration and update label tagging guidelines. Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Yosh <2467194+yoshuawuyts@users.noreply.github.com> --- proposals/0005-structured-labels/README.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/proposals/0005-structured-labels/README.md b/proposals/0005-structured-labels/README.md index afa755c00..ae23a2659 100644 --- a/proposals/0005-structured-labels/README.md +++ b/proposals/0005-structured-labels/README.md @@ -117,6 +117,14 @@ been filed specifically for the agenda, and whether any items need attention. - 2: Explain the finding and close as not planned - 3: Close as not planned +### Rollout + +Inventory label producers and consumers across repositories before renaming labels. +Coordinate updates to release-blocker queries, PR label checks, golden-regeneration +checks, and CI issue creation with the label migration. Keep these paths working +throughout the transition, using temporary support for both names where needed. +Retire old names only after all producers and consumers use the proposed names. + ## New labels | Proposed label | Description | @@ -149,7 +157,7 @@ lot - and I plan for us to use this a lot. Yes! In fact, they almost always should! For example, a bug about MSHV support on Linux should be tagged `O-mshv`, `O-linux`, `C-bug`, and -`S-waiting-on-triage`. +`S-needs-triage`. ### This seems complicated, do we really need it? From a6473699a65841582f9be97bbe5925f564980040 Mon Sep 17 00:00:00 2001 From: Yosh Date: Fri, 23 Oct 2026 12:58:59 +0200 Subject: [PATCH 3/4] update heading Signed-off-by: Yosh --- proposals/0005-structured-labels/README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/proposals/0005-structured-labels/README.md b/proposals/0005-structured-labels/README.md index ae23a2659..dbb45cff1 100644 --- a/proposals/0005-structured-labels/README.md +++ b/proposals/0005-structured-labels/README.md @@ -117,15 +117,7 @@ been filed specifically for the agenda, and whether any items need attention. - 2: Explain the finding and close as not planned - 3: Close as not planned -### Rollout - -Inventory label producers and consumers across repositories before renaming labels. -Coordinate updates to release-blocker queries, PR label checks, golden-regeneration -checks, and CI issue creation with the label migration. Keep these paths working -throughout the transition, using temporary support for both names where needed. -Retire old names only after all producers and consumers use the proposed names. - -## New labels +### New labels | Proposed label | Description | | --------------- | -------------------------------------------- | @@ -142,6 +134,14 @@ Retire old names only after all producers and consumers use the proposed names. | `S-needs-repro` | Needs a repro to confirm the bug | | `S-nominated` | Nominated for discussion in the next meeting | +### Rollout + +Inventory label producers and consumers across repositories before renaming labels. +Coordinate updates to release-blocker queries, PR label checks, golden-regeneration +checks, and CI issue creation with the label migration. Keep these paths working +throughout the transition, using temporary support for both names where needed. +Retire old names only after all producers and consumers use the proposed names. + ## Frequently asked questions ### Why use single-letter prefixes? From a52ec21670d53ee2d30d4f803a3f95b13d03a854 Mon Sep 17 00:00:00 2001 From: Yosh Date: Fri, 23 Oct 2026 13:09:27 +0200 Subject: [PATCH 4/4] more Signed-off-by: Yosh --- proposals/0005-structured-labels/README.md | 26 ++++++++++++++++------ 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/proposals/0005-structured-labels/README.md b/proposals/0005-structured-labels/README.md index dbb45cff1..14e73112d 100644 --- a/proposals/0005-structured-labels/README.md +++ b/proposals/0005-structured-labels/README.md @@ -99,10 +99,10 @@ been filed specifically for the agenda, and whether any items need attention. | `lifecycle/blocked-on-author` | `S-waiting-on-author` | | `lifecycle/confirmed` | `S-confirmed` | | `lifecycle/duplicate` | (1) | -| `lifecycle/fixed` | `S-fixed` | +| `lifecycle/fixed` | (2) | | `lifecycle/needs-review` | `S-needs-triage` | -| `lifecycle/not-a-bug` | (2) | -| `lifecycle/wont-fix` | (3) | +| `lifecycle/not-a-bug` | (3) | +| `lifecycle/wont-fix` | (1) | | `question` | `C-question` | | `ready-for-review` | `S-waiting-on-review` | | `regen-goldens` | `S-needs-golden-regen` | @@ -113,9 +113,9 @@ been filed specifically for the agenda, and whether any items need attention. | `size/xl` | `E-hard` | | `size/xs` | `E-easy` | -- 1: Link issue and close as not planned -- 2: Explain the finding and close as not planned -- 3: Close as not planned +1. Link issue and close as "not planned" +2. Close the issue as "completed" +3. Explain the finding and close as "not planned" ### New labels @@ -180,4 +180,16 @@ up for agendas to discuss as part of triage. ### Why is “participation” labeled with “E-” “Priority” is labeled “P-”, meaning participation needs a different prefix. Rust -uses “E-” which seems as good as any other. +uses “E-” for this, which seems as good as any other choice. + +### Why rename "lifecycle" to "status" + +The term "lifecycle" implies that it can only represent one state at any given +time, e.g. *"Which state in the lifecycle are we on?"*. The term "status" does +not imply that same restriction, and any item can have one or more status +modifiers at any given time. + +This is nice, because it allows us to tag an item as `S-waiting-on-review`, +while also being `S-nominated` for the next community meeting. In comparison: +"nominated for the next meeting" does not feel like it would naturally be part +of any "lifecycle".