guide: document standalone OpenVMM releases

[benhillis]

Summary

Document the standalone pre-1.0 OpenVMM release and support model.

• immutable openvmm-vMAJOR.MINOR.PATCH tags are the public version authority
• normal releases are approximately monthly but quality-gated and sequential
• only the newest release is supported initially
• patch branches are created on demand, with fixes landing in main first
• publication is automatic after builds, checksums, and attestations succeed
• source consumers use a real tag checkout or the official attested source archive
• GitHub automatic source archives are not version-preserving build inputs
• Windows release assets are explicitly unsigned initially

The guide includes normal-release and patch-release maintainer runbooks plus source-consumer verification guidance. Planned artifacts and automation are explicitly marked as under development until the draft implementation lands.

Draft implementation stack: #3989 and benhillis#5, #6, and #7.

[Copilot]

Pull request overview

Adds Guide documentation for a standalone OpenVMM (pre-1.0) release/support model, splitting it from the existing OpenHCL release-branch process and updating related Guide navigation/reference content.

Changes:

• Adds a new Guide page describing OpenVMM release cadence, tag semantics, and maintainer runbooks.
• Re-scopes the existing release management page to OpenHCL and cross-links between OpenVMM/OpenHCL release guidance.
• Updates the CLI reference and Guide SUMMARY to reflect the new documentation structure.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
Guide/src/SUMMARY.md	Splits the previous combined “Releases” entry into distinct OpenVMM vs OpenHCL pages.
Guide/src/reference/openvmm/management/cli.md	Documents --version/-V behavior in the CLI reference.
Guide/src/dev_guide/contrib/release.md	Renames/reframes the page as OpenHCL release management and adds cross-links/admonitions.
Guide/src/dev_guide/contrib/openvmm_release.md	New OpenVMM standalone release model/support policy + normal/patch runbooks.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

Guide/src/dev_guide/contrib/release.md:19

• The opening sentence is duplicated, which reads like a copy/paste error and makes the paragraph awkward.

Occasionally, the OpenHCL project will declare upcoming release milestones. We
Occasionally, the OpenHCL project will declare upcoming release milestones. We

Guide/src/reference/openvmm/management/cli.md:13

• This --version bullet claims a tag/dirty/revision-based version format, but the current CLI uses clap’s built-in --version output (derived from the Cargo package version), which is typically 0.0.0 for in-repo builds. Either update the implementation or keep the docs generic so they stay accurate.

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

Guide/src/reference/openvmm/management/cli.md:13

• The --version / -V description doesn't match the current implementation: Options is derived with clap::Parser and parsed via Options::parse, so clap will print the Cargo package version (it won't include git tag / dirty state / revision metadata as described here). This doc should reflect the actual output, or be softened to avoid specifying git/tag semantics that aren't implemented.

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

Guide/src/reference/openvmm/management/cli.md:13

• The --version description currently claims tag-derived OpenVMM source identity output, but the openvmm CLI is clap-derived and (as of current code) reports the Cargo package version rather than a Git tag/revision-derived OpenVMM product version. This makes the CLI reference misleading until the versioning work lands.

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

Guide/src/dev_guide/contrib/openvmm_release.md:85

• This section describes tag-derived build identity as current behavior, but there doesn’t appear to be an implementation in-tree yet (e.g., no openvmm-v* tag parsing logic, and other code still uses env!("CARGO_PKG_VERSION")). Please mark this as the intended model (or date-qualify it) so readers don’t assume it already reflects openvmm --version today.

OpenVMM resolves its displayed version from source identity:

Guide/src/dev_guide/contrib/openvmm_release.md:98

• This states that openvmm --version prints the tag-derived identity, but current code appears to still rely on Cargo package versioning (e.g., env!("CARGO_PKG_VERSION") in the snapshot manifest). Until the tag-derived identity is implemented, this should be phrased as future/intended behavior (or explicitly note the current behavior).

`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

Guide/src/reference/openvmm/management/cli.md:13

• The --version behavior described here (tag-derived version, +dirty, and Git revision) doesn’t match the current CLI implementation. openvmm_entry::cli_args::parse_options() calls Options::parse without overriding clap’s version string, so --version comes from Cargo package metadata (see openvmm/openvmm_entry/src/cli_args.rs:40-66).

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

Guide/src/dev_guide/contrib/openvmm_release.md:101

• This section describes openvmm --version printing a tag/Git-derived “displayed version”, but the current code uses Cargo package metadata for versioning (e.g., env!("CARGO_PKG_VERSION") is recorded into snapshot manifests in openvmm/openvmm_entry/src/vm_controller.rs:477). Unless the implementation has landed elsewhere, this should be phrased as planned/future behavior to avoid misleading readers.

`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.

A source tree with neither Git metadata nor generated release metadata warns
that `0.0.0-dev` is not an official release identity.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (3)

Guide/src/dev_guide/contrib/openvmm_release.md:89

• This section describes a specific source-identity-derived displayed version scheme, but there is no corresponding implementation in the current tree (no openvmm-v* tag parsing / git-describe logic, and no .openvmm-release.json handling). Since the PR description says planned behavior should be marked as under development, this sentence should be labeled accordingly to avoid implying it is current behavior.

OpenVMM resolves its displayed version from source identity:

Guide/src/dev_guide/contrib/openvmm_release.md:107

• These sentences describe build/CLI behavior (“multiple tags on HEAD fails the build” and openvmm --version printing the concise identity) that is not implemented in the current codebase (openvmm_entry::cli_args::parse_options() just calls Options::parse, and there is no OpenVMM release identity code to drive --version). Mark these as planned/under-development to keep the Guide accurate until the implementation lands.

More than one OpenVMM release tag on `HEAD` fails the build rather than
selecting an arbitrary version.

`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.

Guide/src/reference/openvmm/management/cli.md:13

• This adds a detailed description of --version / -V output, but the current code path (openvmm_entry::cli_args::parse_options() → Options::parse) does not implement an OpenVMM release-identity scheme (no openvmm-v* tag parsing / git-describe logic). To avoid documenting behavior that doesn’t exist yet, mark this flag/output as planned (or remove it until the implementation lands).

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (3)

Guide/src/reference/openvmm/management/cli.md:13

• The new --version / -V description claims Git-tag/dirty/revision-aware output, but the current CLI is parsed via cli_args::Options::parse() (clap derive) without any custom version string. That means --version prints clap's default version (Cargo metadata), not a Git-derived source identity.

* `--version`, `-V`: Prints the concise OpenVMM source identity and exits. A
  clean exact release tag reports `MAJOR.MINOR.PATCH`, a dirty tagged checkout
  adds `+dirty`, and an untagged checkout reports a development version
  containing the source revision.

Guide/src/dev_guide/contrib/openvmm_release.md:107

• Given the build-identity scheme is described as not yet implemented, this should be phrased in future tense (or otherwise scoped) so it doesn't claim current openvmm --version behavior that isn't present in main.

`openvmm --version` prints the concise displayed version. The full source
revision remains available as separate embedded build information.

Guide/src/dev_guide/contrib/openvmm_release.md:90

• This section reads like current behavior (specific 0.0.0-dev+g… formats, dirty tagging, and openvmm --version output), but there is no corresponding git/metadata-based versioning implementation in main today. The PR description says planned automation/artifacts are explicitly marked as under development; this section should be similarly marked or written in future tense to avoid documenting behavior that doesn't exist yet.

## Build identity

OpenVMM resolves its displayed version from source identity:

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

Guide/src/dev_guide/contrib/openvmm_release.md:297

• PR description says publication is automatic after builds/checksums/attestations succeed, but this runbook describes publishing a draft release that a maintainer must review and publish by hand. Please reconcile the Guide text with the intended automation level (or adjust the PR description if the doc is correct).

Tag creation starts the release, but it does not complete it. The workflow
publishes a **draft** GitHub Release, which a maintainer reviews and publishes
by hand. Releasing is new enough that a human should look at the assembled
release before it becomes public.

Guide/src/dev_guide/contrib/openvmm_release.md:252

• PR description mentions Windows release assets being explicitly unsigned initially, but this section says publishing unsigned Windows executables is not acceptable and blocks the binary phase until Authenticode signing exists. Please align the documentation (or PR description) on whether unsigned Windows assets will ever be published in the initial phase.

```admonish warning title="Windows signing is a prerequisite for this phase"
The release workflow cannot Authenticode-sign Windows artifacts today.
Publishing unsigned Windows executables is not acceptable, so Authenticode
signing must land before the binary phase begins. Deferring binaries keeps this
off the critical path for the source release, whose integrity comes from
`SHA256SUMS` and the build provenance attestations.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

Guide/src/dev_guide/contrib/openvmm_release.md:5

• Guide/src/dev_guide/contrib/style_guide.md recommends keeping Guide pages under 400 lines, but this new page is ~461 lines long. Consider splitting the runbooks (normal/patch) into separate sub-pages to keep the policy overview easier to navigate and maintain.

# OpenVMM Release Model and Support

This page describes standalone OpenVMM releases, support policy, source-build
identity, and the maintainer release runbook. OpenVMM versions are independent
from OpenHCL servicing versions.

Guide/src/dev_guide/contrib/openvmm_packaging.md:16

• This page describes verifying release assets (openvmm-<VERSION>-source.tar.gz, SHA256SUMS, attestations), but openvmm_release.md explicitly says the release tooling is not implemented yet and no public release tags should be created. Adding a top-level warning here (similar to openvmm_release.md) would prevent downstream packagers from thinking official release assets already exist.

# Packaging OpenVMM for a Linux Distribution

This page describes building the `openvmm` binary as a Linux distribution
package, from public source only. It is aimed at downstream packagers (for
example, an RPM or `.deb` maintainer) who build from the official OpenVMM source