[pve-devel] [PATCH docs v3 1/1] qm: pve machine version: add section to explain +pveX versions

[Stoiko Ivanov]

some suggestions for rephrasings inline:
On Fri,  4 Apr 2025 14:53:45 +0200
Dominik Csapak <d.csapak at proxmox.com> wrote:

> and clarify what windows guests will be pinned to.
> 
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
> changes from v2:
> * mention that windows gets pinned during guest creation
> 
>  qm.adoc | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/qm.adoc b/qm.adoc
> index 2617a7c..ff49c37 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -173,6 +173,21 @@ This means that after a fresh start, the newest machine version supported by the
>  QEMU binary is used (e.g. the newest machine version QEMU 8.1 supports is
>  version 8.1 for each machine type).
>  
> +PVE Machine Version
> ++++++++++++++++++++
> +
> +Sometimes it's necessary to introduce new defaults or change the existing
> +hardware layout for new guests. For this, we have introduces an additional 'pve
s/introduces/introduced/
but on a meta-level:
https://pve.proxmox.com/wiki/Technical_Writing_Style_Guide#Avoid_first_person

Maybe something like:
Some changes to the default settings or hardware layout are done by {pve}
on top of QEMU's defaults. Those are recorded in the 'pve machine
version'. 
?

> +machine version'. This version begins with 0 with every new QEMU machine
> +version, for example 'pc-q35-9.2+pve0'. When we want to change the hardware
> +layout or a default option, we bump it to the next one (e.g.
> +'pc-q35-9.2+pve1'), so older running guests are not impacted. When pinning a
When a change is done the number after +pve is increased (e.g.
'pc-q35-9.2+pve1') in order to not impact older running guests.

> +guest to a specific machine, this can be omitted. In that case it defaults to
> +0.
If omitted the 'pve machine version' defaults to 0.

> +
> +Windows guests get pinned to the most current version that is available for the
> +specific machine version during guest creation.
We have a similar statement in the paragraph above (for the qemu-machine
version) - maybe shorten this to:
Windows guests 'pve machine version' is pinnned, along with the QEMU
version during guest creation.



> +
>  QEMU Machine Version Deprecation
>  ++++++++++++++++++++++++++++++++
>