Re: [Qemu-devel] [PATCH v2 2/2] docs: document support lifetime for features

[Markus Armbruster]

"Daniel P. Berrange" <address@hidden> writes:

> There is currently no explicit guidance on the duration of support
> for features such as versioned machine types, which have a finite
> useful lifespan. Thus apps / users cannot predict how much time
> they might be able to use a feature for, before it is removed (if
> ever).
>
> This adds a new appendix that lists items which have finite lifecycles,
> such as machine types. For items which are generally expected to be
> supported indefinitely, it sets out the policy around deprecation
> and removal, should it be needed.
>
> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
>  qemu-doc.texi | 34 ++++++++++++++++++++++++++++++++++
>  1 file changed, 34 insertions(+)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 29f89d8..e3c6400 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -37,6 +37,7 @@
>  * QEMU Guest Agent::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Support lifetime::
>  * Deprecations::
>  * License::
>  * Index::
> @@ -3017,6 +3018,39 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> address@hidden Support lifetime
> address@hidden Support lifetime
> +
> +Features provided by QEMU are subject to varying support lifetimes.
> +
> +In general features are intended to be supported indefinitely once
> +introduced. In the event that a feature needs to be removed, there
> +will be some period in which it will be marked as deprecated before
> +eventual removal. All deprecated features will be listed in the
> +``Deprecations'' appendix of this document. They may also generate
> +warnings on the console when QEMU starts up, or if activated via
> +a monitor command.
> +
> +Certain features will have an inherently finite lifetime, and thus
> +will be removed on a fixed schedule.
> +
> address@hidden Machine types
> address@hidden Machine types
> +
> +For architectures which aim to support live migration compatibility
> +across releases, each release will introduce a new versioned machine
> +type. For example, the 2.8.0 release introduced machine types
> +``pc-i440fx-2.8'' and ``pc-q35-2.8' 'for the x86_64/i686 architectures.
> +
> +To allow live migration of a guest running on a 2.8.0 release to a
> +2.9.0, the QEMU 2.9.0 version must support the ``pc-i440fx-2.8'' and
> +``pc-q35-2.8''.  To allow users live migrating VMs to skip multiple

"the ``pc-i440fx-2.8'' and ``pc-q35-2.8'' machine types".

> +intermediate releases when upgrading, new releases of QEMU will
> +support machine types from many previous versions.

Suggest s/many/several/

> +
> +The supported lifetime for machine types is 12 releases, which is
> +equivalent to 4 years worth of previous QEMU releases.
> +

Do we have consensus on this?  Peter?

>  @node Deprecations
>  @appendix Deprecations