From b09be3e6a32ced36736860e8d5c1e7efe05f9607 Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Mon, 3 Aug 2026 21:26:35 +0000 Subject: [PATCH 1/6] docs: propose standalone OpenVMM source releases Document the release flow, alternatives, open identity decisions, and phased implementation plan for maintainer consensus. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- .../contrib/openvmm_release_proposal.md | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 Guide/src/dev_guide/contrib/openvmm_release_proposal.md diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md new file mode 100644 index 0000000000..42019b2042 --- /dev/null +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -0,0 +1,218 @@ +# OpenVMM Standalone Source Release Proposal + +This page proposes how OpenVMM should identify builds and publish standalone +source releases for Linux distributions. + +```admonish important title="Request for consensus" +This is a design proposal, not current release policy. The implementation +should be split into separately reviewed phases only after maintainers agree +on the decisions below. +``` + +## Goals + +The proposal aims to: + +- publish a source archive that distributions can build without repository + metadata or project-specific dependency provisioning; +- validate the exact source archive before it is published; +- give official releases a stable version; +- make development builds distinguishable when useful; +- keep publication manual and reviewable while the process is new; +- avoid release branches, source rewriting, and a two-commit version dance. + +The first release phase publishes source only. Prebuilt binaries and a +long-term servicing policy are out of scope. + +## Proposed release flow + +```text +reviewed version change merges to main + | + v +maintainer manually starts OpenVMM Release + | + v +workflow pins one commit and validates release policy + | + v +assemble source archive and SHA256SUMS once + | + v +build those exact bytes in the distribution configuration + | + v +attest and attach those same bytes to a draft GitHub release + | + v +maintainer reviews the draft and clicks Publish release + | + v +GitHub creates openvmm-v at the pinned commit +``` + +Publishing the draft is the irreversible step. A published tag and its assets +would not be moved or replaced; a correction would use a new version. + +## Proposed source artifact + +The release would contain: + +- `openvmm--source.tar.gz`; +- `SHA256SUMS`; +- GitHub build provenance attestations for both published files. + +The archive would be a deterministic export of the tracked tree at one commit, +rooted at `openvmm-/`. It would not contain `.git`, prebuilt native +dependencies, vendored Rust crates, or pipeline-generated version metadata. + +The version would already be present in the root `Cargo.toml`. Release assembly +would not rewrite the tree or inject a second copy of the version. + +## Proposed distribution-build gate + +The release workflow would assemble the archive once and transfer it through +validation and publication as an internal workflow artifact. The distribution +gate would: + +1. verify `SHA256SUMS`; +2. extract outside the repository checkout; +3. confirm the archive has no `.git` directory; +4. build OpenVMM with `--locked` and system dependencies; +5. confirm the resulting binary reports the expected product version; +6. confirm it dynamically links the system OpenSSL. + +Normal pull-request CI would run the same assembly and distribution-build +logic against the commit under test. It must independently assemble its own +snapshot because no release preparation job exists in ordinary CI. + +## Decisions requiring consensus + +### 1. Canonical product version + +**Proposal:** Store a stable `MAJOR.MINOR.PATCH` in +`[workspace.package] version` in the root `Cargo.toml`. Keep the most recently +released version until a reviewed pull request selects the next version. + +This makes the version available to Cargo and to downstream builders without +requiring Git metadata. + +**Alternative:** Derive the product version from a tag or pipeline input. + +The alternative avoids a committed release version, but source archives would +need generated metadata or a build-time override, creating another identity +source that could disagree with the tree. + +### 2. Development-build identity + +**Proposal:** A normal Git checkout reports +`+g<9-character-commit>`, identified as a development build. + +This distinguishes commits made after the latest release even while the +committed product version remains unchanged. + +**Simpler alternative:** Report plain `` for every build and expose +the commit only through a separate detailed version field. + +This is the largest open design question. The simpler alternative requires +less build logic but makes concise version output ambiguous between an +official release and an arbitrary checkout. + +### 3. Exact release-tag checkout + +**Proposal:** A checkout reports an official release identity only when +exactly one `openvmm-v` tag points at `HEAD`. Missing, mismatched, or +ambiguous release tags fall back to development identity. + +**Alternative:** Treat every Git checkout as development, including an exact +release-tag checkout. + +The alternative is simpler and leaves provenance as the only proof of an +official build, but developers rebuilding a release tag would not get the same +concise version as archive builders. + +### 4. Build from an extracted archive + +**Proposal:** A build with no applicable Git repository reports plain +`` as a release-shaped build. + +The published archive necessarily lacks `.git`, so the committed Cargo version +is the only identity available. + +This classification is descriptive, not proof that arbitrary Git-free source +is official. Consumers must verify the source archive's checksum and +provenance attestation. + +**Alternative:** Require the release pipeline or packager to set an explicit +official-build variable. + +The alternative makes official status explicit but requires mutable build +inputs and makes rebuilding the unmodified published archive behave +differently unless every packager reproduces the release environment. + +### 5. Distribution package override + +**Proposal:** Allow a builder to set `OPENVMM_PKGVERSION` and classify the +result as a custom build. + +This lets a distribution expose its package release, for example +`0.2.0-4`, without claiming that its binary is the project-produced official +build. + +**Alternative:** Omit the override and require package metadata to remain +outside the OpenVMM binary. + +### 6. Identity integration surfaces + +The prototype exposes identity through: + +- concise `openvmm -V`; +- detailed `openvmm --version`; +- startup telemetry; +- saved-state product metadata; +- an extractable binary metadata section; +- Windows VERSIONINFO, including a prerelease flag for development builds. + +These surfaces do not need to be accepted as one decision. The minimum useful +implementation could start with CLI output and add other integrations only +when their consumers and value are clear. + +### 7. Manual draft publication + +**Proposal:** A manually dispatched workflow creates a draft GitHub release. +A maintainer reviews the ordinary GitHub draft and clicks **Publish release**, +which creates the tag at the workflow's pinned commit. + +**Alternative:** Push the tag first and trigger release automation from it. + +Publishing the draft last avoids creating an official tag before archive +validation succeeds. The tradeoff is that the release workflow must validate +tag availability and rely on a human for the final action. + +## Proposed implementation phases + +After consensus, implementation would be divided into independently reviewed +pull requests: + +1. establish the canonical Cargo product version; +2. implement only the agreed build-identity behavior and integrations; +3. add deterministic source assembly and the distribution-build CI gate; +4. add generic GitHub release and provenance helpers; +5. add the manual OpenVMM release workflow and maintainer documentation. + +Generated workflow files would land with the Flowey source that produces them. +Each phase would remain buildable and testable before the next phase begins. + +## Review guidance + +Reviewers should focus first on the seven decisions above rather than detailed +implementation. In particular: + +- Is distinguishing development builds in concise version output valuable? +- Should an exact release-tag checkout receive release identity? +- Should Git-free archive builds be release-shaped or require an override? +- Which identity integration surfaces have demonstrated consumers? +- Is manual draft publication the right initial safety boundary? + +Implementation details should be revised or removed when they do not follow +from an accepted decision. From 6cf5931de18fc2cdfc8238ce638340b3920a382e Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Mon, 3 Aug 2026 21:37:49 +0000 Subject: [PATCH 2/6] docs: simplify the proposed distribution gate Limit the initial gate to extracting and building the exact release archive, deferring policy-specific assertions until maintainers agree they are required. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- .../contrib/openvmm_release_proposal.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md index 42019b2042..6f41714552 100644 --- a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -75,12 +75,20 @@ The release workflow would assemble the archive once and transfer it through validation and publication as an internal workflow artifact. The distribution gate would: -1. verify `SHA256SUMS`; -2. extract outside the repository checkout; -3. confirm the archive has no `.git` directory; -4. build OpenVMM with `--locked` and system dependencies; -5. confirm the resulting binary reports the expected product version; -6. confirm it dynamically links the system OpenSSL. +1. consume the exact archive intended for publication; +2. extract it outside the repository checkout; +3. run `cargo build --release --locked -p openvmm` using system dependencies. + +The initial gate would answer one question: can a distribution build the source +artifact without relying on the project checkout or project-provisioned native +dependencies? + +Checksum verification, an explicit `.git` assertion, binary-version +validation, and direct OpenSSL linkage inspection are possible follow-up +checks. They should be added only when maintainers agree that each check +enforces a release requirement worth owning. In particular, binary-version +validation depends on the unresolved build-identity design and is not part of +the initial gate. Normal pull-request CI would run the same assembly and distribution-build logic against the commit under test. It must independently assemble its own From 187b5ec6579ad4253b0292e96b43928e637cb6b4 Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Mon, 3 Aug 2026 22:01:46 +0000 Subject: [PATCH 3/6] docs: clarify release RFC decision status Record the preferred archive, package, CLI, and publication directions while keeping development and exact-tag identities open for maintainer feedback. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- .../contrib/openvmm_release_proposal.md | 65 ++++++++++++------- 1 file changed, 43 insertions(+), 22 deletions(-) diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md index 6f41714552..936caa3226 100644 --- a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -96,8 +96,15 @@ snapshot because no release preparation job exists in ordinary CI. ## Decisions requiring consensus +The statuses below record the proposal author's current direction. **Open +question** means maintainers are specifically being asked to choose between the +alternatives. **Proposed direction** means feedback is still welcome, but the +RFC recommends that choice. + ### 1. Canonical product version +**Status: Proposed direction** + **Proposal:** Store a stable `MAJOR.MINOR.PATCH` in `[workspace.package] version` in the root `Cargo.toml`. Keep the most recently released version until a reviewed pull request selects the next version. @@ -113,6 +120,8 @@ source that could disagree with the tree. ### 2. Development-build identity +**Status: Open question** + **Proposal:** A normal Git checkout reports `+g<9-character-commit>`, identified as a development build. @@ -124,10 +133,13 @@ the commit only through a separate detailed version field. This is the largest open design question. The simpler alternative requires less build logic but makes concise version output ambiguous between an -official release and an arbitrary checkout. +official release and an arbitrary checkout. Maintainer feedback should decide +which behavior the initial implementation uses. ### 3. Exact release-tag checkout +**Status: Open question** + **Proposal:** A checkout reports an official release identity only when exactly one `openvmm-v` tag points at `HEAD`. Missing, mismatched, or ambiguous release tags fall back to development identity. @@ -137,10 +149,13 @@ release-tag checkout. The alternative is simpler and leaves provenance as the only proof of an official build, but developers rebuilding a release tag would not get the same -concise version as archive builders. +concise version as archive builders. Maintainer feedback should decide whether +exact-tag detection is worth its additional build logic. ### 4. Build from an extracted archive +**Status: Proposed direction** + **Proposal:** A build with no applicable Git repository reports plain `` as a release-shaped build. @@ -160,33 +175,37 @@ differently unless every packager reproduces the release environment. ### 5. Distribution package override -**Proposal:** Allow a builder to set `OPENVMM_PKGVERSION` and classify the -result as a custom build. +**Status: Proposed direction** + +**Proposal:** Do not add a package-version override. The OpenVMM binary reports +the committed product version, while a distribution records its package +revision in its own package metadata. -This lets a distribution expose its package release, for example -`0.2.0-4`, without claiming that its binary is the project-produced official -build. +This is independent of release identity. Builds from the published archive +already recover the committed Cargo version without an environment variable. -**Alternative:** Omit the override and require package metadata to remain -outside the OpenVMM binary. +**Alternative:** Add an `OPENVMM_PKGVERSION` environment variable that replaces +the displayed identity with builder-supplied text and classifies the result as +a custom build. + +The alternative gives downstream packagers another identity surface to manage +and is not required to build an official source archive. ### 6. Identity integration surfaces -The prototype exposes identity through: +**Status: Proposed direction** -- concise `openvmm -V`; -- detailed `openvmm --version`; -- startup telemetry; -- saved-state product metadata; -- an extractable binary metadata section; -- Windows VERSIONINFO, including a prerelease flag for development builds. +**Proposal:** Limit the initial implementation to concise `openvmm -V` and +detailed `openvmm --version` output. -These surfaces do not need to be accepted as one decision. The minimum useful -implementation could start with CLI output and add other integrations only -when their consumers and value are clear. +Startup telemetry, saved-state metadata, an extractable binary metadata +section, and Windows VERSIONINFO changes would be separate follow-up proposals. +They should be added only when their consumers and value are clear. ### 7. Manual draft publication +**Status: Proposed direction** + **Proposal:** A manually dispatched workflow creates a draft GitHub release. A maintainer reviews the ordinary GitHub draft and clicks **Publish release**, which creates the tag at the workflow's pinned commit. @@ -218,9 +237,11 @@ implementation. In particular: - Is distinguishing development builds in concise version output valuable? - Should an exact release-tag checkout receive release identity? -- Should Git-free archive builds be release-shaped or require an override? -- Which identity integration surfaces have demonstrated consumers? -- Is manual draft publication the right initial safety boundary? +- Are there objections to Git-free archive builds using the committed version? +- Is there a demonstrated need for a downstream package-version override? +- Are CLI outputs sufficient for the initial identity implementation? +- Are there objections to manual draft publication as the initial safety + boundary? Implementation details should be revised or removed when they do not follow from an accepted decision. From 466af7ab12dfdc004ae9be41770dbcbd8646ec3a Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Mon, 3 Aug 2026 22:10:12 +0000 Subject: [PATCH 4/6] docs: make Cargo the sole product version source Remove tag- and workflow-derived product versions from the release proposal alternatives. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- Guide/src/dev_guide/contrib/openvmm_release_proposal.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md index 936caa3226..6e3c058967 100644 --- a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -112,12 +112,6 @@ released version until a reviewed pull request selects the next version. This makes the version available to Cargo and to downstream builders without requiring Git metadata. -**Alternative:** Derive the product version from a tag or pipeline input. - -The alternative avoids a committed release version, but source archives would -need generated metadata or a build-time override, creating another identity -source that could disagree with the tree. - ### 2. Development-build identity **Status: Open question** From cd9739aa04e7e1a66dec567ed32303baeaf2dd2e Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Tue, 4 Aug 2026 10:41:06 -0700 Subject: [PATCH 5/6] Guide: resolve checkout identity feedback Choose revision-suffixed identity for every Git checkout, clarify system dependencies, and document correction releases. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- .../contrib/openvmm_release_proposal.md | 52 ++++++++----------- 1 file changed, 23 insertions(+), 29 deletions(-) diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md index 6e3c058967..4cb9a1d4a9 100644 --- a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -52,7 +52,8 @@ GitHub creates openvmm-v at the pinned commit ``` Publishing the draft is the irreversible step. A published tag and its assets -would not be moved or replaced; a correction would use a new version. +would not be moved or replaced. A correction would use a normal reviewed pull +request to select a new patch version, followed by a new release. ## Proposed source artifact @@ -83,6 +84,11 @@ The initial gate would answer one question: can a distribution build the source artifact without relying on the project checkout or project-provisioned native dependencies? +The standalone GNU/Linux build does not use `openvmm-deps`. CI would install +the distribution's C toolchain, Linux headers, OpenSSL development package, +`pkg-config`, and Protocol Buffers compiler. OpenHCL, test, and firmware assets +from `openvmm-deps` are outside this build. + Checksum verification, an explicit `.git` assertion, binary-version validation, and direct OpenSSL linkage inspection are possible follow-up checks. They should be added only when maintainers agree that each check @@ -96,10 +102,11 @@ snapshot because no release preparation job exists in ordinary CI. ## Decisions requiring consensus -The statuses below record the proposal author's current direction. **Open -question** means maintainers are specifically being asked to choose between the -alternatives. **Proposed direction** means feedback is still welcome, but the -RFC recommends that choice. +The statuses below record the proposal author's current direction. **Chosen +direction** records a decision supported by current maintainer feedback. +**Open question** means maintainers are specifically being asked to choose +between alternatives. **Proposed direction** means feedback is still welcome, +but the RFC recommends that choice. ### 1. Canonical product version @@ -114,37 +121,26 @@ requiring Git metadata. ### 2. Development-build identity -**Status: Open question** +**Status: Chosen direction** **Proposal:** A normal Git checkout reports `+g<9-character-commit>`, identified as a development build. This distinguishes commits made after the latest release even while the -committed product version remains unchanged. - -**Simpler alternative:** Report plain `` for every build and expose -the commit only through a separate detailed version field. - -This is the largest open design question. The simpler alternative requires -less build logic but makes concise version output ambiguous between an -official release and an arbitrary checkout. Maintainer feedback should decide -which behavior the initial implementation uses. - -### 3. Exact release-tag checkout +committed product version remains unchanged and makes the source commit obvious +in concise version output. -**Status: Open question** +### 3. Git checkout classification -**Proposal:** A checkout reports an official release identity only when -exactly one `openvmm-v` tag points at `HEAD`. Missing, mismatched, or -ambiguous release tags fall back to development identity. +**Status: Chosen direction** -**Alternative:** Treat every Git checkout as development, including an exact -release-tag checkout. +**Proposal:** Treat every Git checkout as development, including an exact +checkout of an `openvmm-v` release tag. -The alternative is simpler and leaves provenance as the only proof of an -official build, but developers rebuilding a release tag would not get the same -concise version as archive builders. Maintainer feedback should decide whether -exact-tag detection is worth its additional build logic. +Only a Git-free source tree reports plain ``. Release tags remain +publication markers and are not build-identity inputs. This avoids special tag +detection and ensures that locally rebuilt checkouts never claim official +release identity. ### 4. Build from an extracted archive @@ -229,8 +225,6 @@ Each phase would remain buildable and testable before the next phase begins. Reviewers should focus first on the seven decisions above rather than detailed implementation. In particular: -- Is distinguishing development builds in concise version output valuable? -- Should an exact release-tag checkout receive release identity? - Are there objections to Git-free archive builds using the committed version? - Is there a demonstrated need for a downstream package-version override? - Are CLI outputs sufficient for the initial identity implementation? From 7601e452fa47cdd246adbb12fe7ba3790a282b5a Mon Sep 17 00:00:00 2001 From: Ben Hillis Date: Wed, 5 Aug 2026 10:51:12 -0700 Subject: [PATCH 6/6] Guide: defer source commit identity Record that Git-free builds need only the committed product version initially and that another source-commit surface can be added later if needed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4fe65aa5-d620-4856-a525-e32bf98c16b1 --- Guide/src/dev_guide/contrib/openvmm_release_proposal.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md index 4cb9a1d4a9..ddd2509f65 100644 --- a/Guide/src/dev_guide/contrib/openvmm_release_proposal.md +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -92,9 +92,8 @@ from `openvmm-deps` are outside this build. Checksum verification, an explicit `.git` assertion, binary-version validation, and direct OpenSSL linkage inspection are possible follow-up checks. They should be added only when maintainers agree that each check -enforces a release requirement worth owning. In particular, binary-version -validation depends on the unresolved build-identity design and is not part of -the initial gate. +enforces a release requirement worth owning. Binary-version validation is not +part of the initial gate. Normal pull-request CI would run the same assembly and distribution-build logic against the commit under test. It must independently assemble its own @@ -152,6 +151,10 @@ release identity. The published archive necessarily lacks `.git`, so the committed Cargo version is the only identity available. +The initial binary identity does not separately expose the source commit for a +Git-free build. The release tag, target, and provenance identify the published +source, and another binary surface can be added later if needed. + This classification is descriptive, not proof that arbitrary Git-free source is official. Consumers must verify the source archive's checksum and provenance attestation.