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..ddd2509f65 --- /dev/null +++ b/Guide/src/dev_guide/contrib/openvmm_release_proposal.md @@ -0,0 +1,238 @@ +# 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 normal reviewed pull +request to select a new patch version, followed by a new release. + +## 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. 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? + +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 +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 +snapshot because no release preparation job exists in ordinary CI. + +## Decisions requiring consensus + +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 + +**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. + +This makes the version available to Cargo and to downstream builders without +requiring Git metadata. + +### 2. Development-build identity + +**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 and makes the source commit obvious +in concise version output. + +### 3. Git checkout classification + +**Status: Chosen direction** + +**Proposal:** Treat every Git checkout as development, including an exact +checkout of an `openvmm-v` release tag. + +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 + +**Status: Proposed direction** + +**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. + +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. + +**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 + +**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 is independent of release identity. Builds from the published archive +already recover the committed Cargo version without an environment variable. + +**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 + +**Status: Proposed direction** + +**Proposal:** Limit the initial implementation to concise `openvmm -V` and +detailed `openvmm --version` output. + +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. + +**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: + +- 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.