VEP-282: VEP Proposal Governance by EdDev · Pull Request #283 · kubevirt/enhancements

EdDev · 2026-04-20T16:59:08Z

VEP Metadata

Tracking issue: #282

SIG label:
/sig compute
/sig network
/sig storage

What this PR does

Introduces VEP #282 — a meta-VEP proposing a formal proposal governance layer for the VEP
process. This adds explicit lifecycle states for VEP documents, structured YAML front matter
metadata, formal reviewer/approver assignment, CI enforcement of state transitions and VEP
Freeze dates, and AI-assisted authoring guidance via CLAUDE.md.

Special notes for your reviewer

This is a meta-VEP targeting GA for v1.9, so the governance tooling and process are in place
before the v1.10 VEP season begins.

kubevirt-bot · 2026-04-20T16:59:13Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign xpivarc for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

EdDev · 2026-04-20T17:41:02Z

/cc @iholder101

iholder101

Thanks @EdDev! Generally looks great to me!

iholder101 · 2026-04-23T09:35:46Z

+2. A target milestone is set in the front matter.
+3. The merge happens before the VEP Freeze for that release.
+
+### VEP Front Matter


That's a great idea. This opens the door to introduce a linter to auto-check if something's missing and to more easily generate a status report programmatically 👍

iholder101 · 2026-04-23T09:37:06Z

+---
+title: Short descriptive title
+vep-number: NNNN          # equals the tracking issue number; set on issue creation
+creation-date: "YYYY-MM-DD"


it this really needed? It could be inferred from the VEP issue/PR creation date, no?

I think it is used to help with the processing of automation.
In the end the final document is persisted and one can read it without handling git or GitHub PR information.

iholder101 · 2026-04-23T09:37:47Z

+reviewers:
+  - TBD                   # replaced by real handles after SIG triage;
+                          # must be filled before targeting a release
+approvers:
+  - TBD                   # SIG chairs/leads who commit to approving the design;
+                          # must be filled before targeting a release


I guess these are mandatory in order to become implementable?

Yes, it is validated by the CI (see "Field rules enforced by CI:").
Do you suggest to change the comment?

iholder101 · 2026-04-23T09:38:10Z

+  - TBD                   # SIG chairs/leads who commit to approving the design;
+                          # must be filled before targeting a release
+
+feature-gate: FeatureName # omit field only if VEP body contains explicit opt-out justification


Do we need a list here?

We could, I have no strong opinion.
I think we usually use one per VEP, unlike in K8S where each component may have one for the same feature.

This came up during the sig-compute call yesterday but what about listing any FGs the VEP is dependent on?

@lyarwood , do you refer to features that depend on other features that have FGs?
I do not have a problem to have a list, however, I find it problematic to depend on a FG from a different VEP.
We should probably discuss inter VEP dependency as a follow up.

Bottom line, do you also suggest to convert this to a list? If you can, please give some reasoning so we will have this on record, if we ever revisit this.

iholder101 · 2026-04-23T09:40:47Z

+milestone:
+  alpha: "v1.x"
+  beta: "v1.x"            # omit until planned
+  ga: "v1.x"              # omit until planned


Kubernetes have another "latest-milestone" field. The idea is that it captures the latest version in which work was done, even if it wasn't complete.

As an example, if a VEP tried to graduate to beta in v1.x but didn't make it to the code freeze, it would be captured here.

Do you think we need something like that?

I questioned the need of this as well.
We have the (current) "stage" and milestones. I thought that given that, we do not need anything else or that it can be tracked on the issue tracker.

We could add it or we can wait for it to be needed.
I guess once we start automating things, we will know better.

Just let me know if you have any strong opinion on this.

iholder101 · 2026-04-23T10:05:02Z

+1. **First merge (`provisional`)**: The initial VEP PR is merged with `status: provisional`.
+   This signals that the owning SIG accepts the proposal as worth pursuing. It does not
+   require the design to be final or complete.
+2. **Second merge (`implementable`)**: A follow-up VEP update PR changes the status to
+   `implementable`. This is the SIG approvers explicitly blessing the design as ready for
+   implementation. This PR must be merged before the VEP Freeze for the targeted release.


Is it acceptable for the initial PR to be marked as implementable if it assigned reviewers / approvers?

Also - let's say we agree on a VEP's design, but there's no one willing to implement it in the foreseen future (say for bandwidth and priority reasons) - should we spend the time on reviewing and merging the VEP PR, or defer it? The review itself also carries bandwidth from the reviewers

Is it acceptable for the initial PR to be marked as implementable if it assigned reviewers / approvers?

I think the criteria is if the VEP can be merged before the VEP freeze, which implies this second merge.
I will update the wording so it will be clearer that the first is optional.

Also - let's say we agree on a VEP's design, but there's no one willing to implement it in the foreseen future (say for bandwidth and priority reasons) - should we spend the time on reviewing and merging the VEP PR, or defer it? The review itself also carries bandwidth from the reviewers

Ideally, IMO it should be consider as part of the VEP triage of the SIG, taking this into consideration when prioritizing.
Should we formally express this commitment? I am not sure, it may be too hard and demanding. But if you think it is better to do it formally, then how would you want to express it?
I do not have a strong opinion on this, but I have a feeling we could start with a soft consideration (internally) and only if we find it as a problem, to express it formally in the VEP requirements.

lyarwood · 2026-04-23T12:39:15Z

+- There is no formal state to express that a VEP has been deferred, rejected, withdrawn,
+  or superseded by another proposal.
+- Reviewer and approver assignment is described in the README as a SIG responsibility, but
+  there is no structured place in the VEP document to record who has committed to this role.


I'd say all of these are informally tracked on the release project at the moment instead of directly in the VEP itself.

Right, I'll update the wording.
Done

lyarwood · 2026-04-23T12:41:13Z

+- Automate enforcement of the VEP Freeze date via CI, with a maintainer-controlled exception path.
+- Validate front matter completeness and state-transition correctness on every PR.
+- Leverage the existing Prow blunderbuss plugin (already active for the org) to suggest reviewers
+  from SIG-level OWNERS files once those files are populated.


100% this, I still don't know why we've been so slow at implementing this.

lyarwood · 2026-04-23T12:44:38Z

+| `provisional` | VEP is open for design discussion | Author, at PR open | PR creation |
+| `implementable` | Design approved; VEP is tracked for a release | SIG approvers, at PR merge | VEP Freeze |
+| `implemented` | Feature has reached GA; VEP is complete | Author + SIG | After GA code merges |
+| `deferred` | Not actively progressing; removed from release tracking | SIG | Any time |


I assume withdrawn VEPs can move back to provisional eventually?

What about implementable? I assume it moves back to provisional until another PR lands moving the target version(s) forward?

I think it goes like this:

From withdrawn it makes sense to reset the process, i.e. to start over and re-evaluate the idea before accepting it as "provisional". In practice this means it can move to "replaced" (or "rejected").

Implementable means all VEP details are in place and got approved to a specific target release. The release could be changed if the implementation is not completed, but I do not see it getting back to "provisional". It can however move to "replaced" in case it got stuck and another VEP took over to continue the work.

lyarwood · 2026-04-23T12:47:36Z

+  - TBD                   # SIG chairs/leads who commit to approving the design;
+                          # must be filled before targeting a release
+
+feature-gate: FeatureName # omit field only if VEP body contains explicit opt-out justification


This came up during the sig-compute call yesterday but what about listing any FGs the VEP is dependent on?

lyarwood · 2026-04-23T12:49:22Z

+
+The label is registered in `kubevirt/project-infra` (the Prow label configuration) and
+applied via the Prow `label` plugin using the `/kind vep` command, or automatically by CI.
+


What about state labels for VEPs?

Used in combination with the existing SIG labels it would give folks a quick way of filtering open PRs ahead of freeze etc.

This is surely possible.
At the moment, the filtering and the management is handled by the project board and CI/automation tooling can assist to fill it up.

I guess we can follow up on this either way.

lyarwood · 2026-04-23T12:50:39Z

+
+### Agentic AI Assistance
+
+The project-level `CLAUDE.md` is updated with VEP governance instructions so that


https://agents.md/ to be a little more generic.

Oh, sorry to miss this :D

As a general opinion - I'm not sold on the idea of us maintaining an agents.md or claude.md files TBH.

I generalized it, thanks. Done
Most projects add a soft link to it (i.e. CLAUDE.md is a soft link to AGENTS.md).

@iholder101 , the storm is already at our doorsteps, and these have become pretty standard tools nowadays. The project enforces best practices and structures the tooling at some base level and individual contributors may add their own enhancements at their local workspace (e.g. CLAUDE.local.md).

For the project, its value is with allowing contributors to prepare better VEPs and lower the effort needed to review them. Other tools will most likely depend on these as well in the future.

vladikr · 2026-04-23T20:10:15Z

+  A VEP can be proposed as tracking a release after the freeze with no CI guard.
+
+The Kubernetes KEP process addresses the first gap with a `status:` field
+(`provisional → implementable → implemented` and terminal states), and an explicit


yes, currently, we just call these differently in the tracker:
provisional = proposed for consideration
implementable= tracked

I updated the text that it is tracked through the project board. Done

vladikr · 2026-04-23T20:18:39Z

I think it's a great proposal, thank you @EdDev !
This will allow us to make the VEP police agent even more powerful and focused.

One thing that i think is missing is a clarification around the source of truth.

I'd add that the VEP document (specifically its YAML front matter) is the single source of truth for status and metadata.
All status transitions, especially the provisional to implementable, MUST be done by updating the front matter via a PR.
The VEP police agent, GitHub Projects board, and any CI checks MUST derive the current state only from the front matter.

The only beurocratic problem that I see is that the author or shepherd will need to open a PR, after a design VEP PR merges (or maybe approve an auto generated PR) to change the status to implementable.
I guess the the VEP police agent may proactively open such PRs.

Adds a foundation meta-VEP proposing formal proposal governance for the VEP process: explicit lifecycle states, structured YAML front matter, formal reviewer/approver assignment as a capacity and commitment signal, CI enforcement of VEP Freeze dates, and SIG-level OWNERS files for Prow blunderbuss reviewer suggestions. Targets GA for v1.9 so the new model is in place before the v1.10 VEP season begins. Assisted-by: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Edward Haas <edwardh@redhat.com>

EdDev

One thing that i think is missing is a clarification around the source of truth.

I'd add that the VEP document (specifically its YAML front matter) is the single source of truth for status and metadata. All status transitions, especially the provisional to implementable, MUST be done by updating the front matter via a PR. The VEP police agent, GitHub Projects board, and any CI checks MUST derive the current state only from the front matter.

I have added it to the text, thank you!

The only beurocratic problem that I see is that the author or shepherd will need to open a PR, after a design VEP PR merges (or maybe approve an auto generated PR) to change the status to implementable. I guess the the VEP police agent may proactively open such PRs.

Yes, and I think the effort it minor. Once we understand better the steps from practicing it, we can automate most if it easily.

EdDev · 2026-04-24T06:33:17Z

+  - TBD                   # SIG chairs/leads who commit to approving the design;
+                          # must be filled before targeting a release
+
+feature-gate: FeatureName # omit field only if VEP body contains explicit opt-out justification


@lyarwood , do you refer to features that depend on other features that have FGs?
I do not have a problem to have a list, however, I find it problematic to depend on a FG from a different VEP.
We should probably discuss inter VEP dependency as a follow up.

Bottom line, do you also suggest to convert this to a list? If you can, please give some reasoning so we will have this on record, if we ever revisit this.

EdDev · 2026-04-24T06:35:26Z

+- There is no formal state to express that a VEP has been deferred, rejected, withdrawn,
+  or superseded by another proposal.
+- Reviewer and approver assignment is described in the README as a SIG responsibility, but
+  there is no structured place in the VEP document to record who has committed to this role.


Right, I'll update the wording.
Done

EdDev · 2026-04-24T06:36:44Z

+  A VEP can be proposed as tracking a release after the freeze with no CI guard.
+
+The Kubernetes KEP process addresses the first gap with a `status:` field
+(`provisional → implementable → implemented` and terminal states), and an explicit


I updated the text that it is tracked through the project board. Done

EdDev · 2026-04-24T06:51:10Z

+| `provisional` | VEP is open for design discussion | Author, at PR open | PR creation |
+| `implementable` | Design approved; VEP is tracked for a release | SIG approvers, at PR merge | VEP Freeze |
+| `implemented` | Feature has reached GA; VEP is complete | Author + SIG | After GA code merges |
+| `deferred` | Not actively progressing; removed from release tracking | SIG | Any time |


I think it goes like this:

From withdrawn it makes sense to reset the process, i.e. to start over and re-evaluate the idea before accepting it as "provisional". In practice this means it can move to "replaced" (or "rejected").

Implementable means all VEP details are in place and got approved to a specific target release. The release could be changed if the implementation is not completed, but I do not see it getting back to "provisional". It can however move to "replaced" in case it got stuck and another VEP took over to continue the work.

EdDev · 2026-04-24T07:03:44Z

+
+The label is registered in `kubevirt/project-infra` (the Prow label configuration) and
+applied via the Prow `label` plugin using the `/kind vep` command, or automatically by CI.
+


This is surely possible.
At the moment, the filtering and the management is handled by the project board and CI/automation tooling can assist to fill it up.

I guess we can follow up on this either way.

EdDev · 2026-04-24T07:15:09Z

+
+### Agentic AI Assistance
+
+The project-level `CLAUDE.md` is updated with VEP governance instructions so that


I generalized it, thanks. Done
Most projects add a soft link to it (i.e. CLAUDE.md is a soft link to AGENTS.md).

@iholder101 , the storm is already at our doorsteps, and these have become pretty standard tools nowadays. The project enforces best practices and structures the tooling at some base level and individual contributors may add their own enhancements at their local workspace (e.g. CLAUDE.local.md).

For the project, its value is with allowing contributors to prepare better VEPs and lower the effort needed to review them. Other tools will most likely depend on these as well in the future.

EdDev · 2026-04-26T10:48:29Z

change: Answered review comments.

kubevirt-bot added sig/compute dco-signoff: yes Indicates the PR's author has DCO signed all their commits. sig/network labels Apr 20, 2026

kubevirt-bot requested review from lyarwood, vladikr and xpivarc April 20, 2026 16:59

kubevirt-bot added sig/storage size/L labels Apr 20, 2026

EdDev mentioned this pull request Apr 20, 2026

VEP 282: VEP Proposal Governance #282

Open

4 tasks

kubevirt-bot requested a review from iholder101 April 20, 2026 17:41

iholder101 reviewed Apr 23, 2026

View reviewed changes

lyarwood reviewed Apr 23, 2026

View reviewed changes

vladikr reviewed Apr 23, 2026

View reviewed changes

EdDev commented Apr 26, 2026

View reviewed changes

EdDev force-pushed the vep-proposal-governance branch from c9b3dfd to dfec33b Compare April 26, 2026 10:48

EdDev requested review from iholder101, lyarwood and vladikr April 26, 2026 10:49


		The label is registered in `kubevirt/project-infra` (the Prow label configuration) and
		applied via the Prow `label` plugin using the `/kind vep` command, or automatically by CI.


		### Agentic AI Assistance

		The project-level `CLAUDE.md` is updated with VEP governance instructions so that

Conversation

EdDev commented Apr 20, 2026

VEP Metadata

What this PR does

Special notes for your reviewer

Uh oh!

kubevirt-bot commented Apr 20, 2026

Uh oh!

EdDev commented Apr 20, 2026

Uh oh!

iholder101 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vladikr commented Apr 23, 2026

Uh oh!

EdDev left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!