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.

[benhillis]

This is the primary downside of git tag based versioning, but I think it is still preferrable over a checked in version file that needs to be updated for each release.

[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 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 description doesn't match current behavior: openvmm_entry::Options is a plain #[derive(Parser)] without a custom version string, so Clap's built-in --version/-V prints the Cargo package version rather than a tag/dirty/source-revision identity. Either document the current output or clearly mark the tag-derived/source-identity output as under development (and link to the release-model page).

* `--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:90

• This section documents a specific source-identity/version-string scheme (0.0.0-dev+g..., +dirty, build failure on multiple tags), but that behavior does not appear to be implemented in the current tree (and openvmm_entry does not override Clap's default --version). To avoid the Guide becoming incorrect, mark this build-identity behavior as under development (similar to the later runbook note) or reword it as a proposed/target model.

## Build identity

OpenVMM resolves its displayed version from source identity: