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

[Thomas Huth]

On 04.07.2017 13:14, Daniel P. Berrange wrote:
> 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.

Great, thanks for tackling this!

> Signed-off-by: Daniel P. Berrange <address@hidden>
> ---
>  qemu-doc.texi | 37 +++++++++++++++++++++++++++++++++++++
>  1 file changed, 37 insertions(+)
> 
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 21079fd..27781e4 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -38,6 +38,7 @@
>  * QEMU Guest Agent::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Support lifetime::
>  * License::
>  * Index::
>  @end menu
> @@ -3017,6 +3018,42 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> address@hidden Support lifetime
> address@hidden Support lifetime
> +
> +In general features are intended to be supported indefinitely once
> +introduced into QEMU.
> +
> +In the event that a feature needs to be removed, it will be listed
> +in the ``Deprecated features'' appendix of this document. The feature
> +will remain functional for 2 major releases prior to actual removal.

Maybe say "at least for two major releases" instead? Sometimes we might
forget to remove it in time, or we might decide to keep it alive a
little bit longer in case it was once an important feature...

> +Deprecated features may also generate warnings on the console when
> +QEMU starts up, or if activated via a monitor command, however,
> +this is not a mandatory requirement.
> +
> +Certain features have an inherently finite lifetime, and thus
> +will be removed on a fixed schedule, without following the normal
> +deprecation process. Such features are listed in the sections
> +that follow.
> +
> 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.

Space at wrong location --------------^

> +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
> +intermediate releases when upgrading, new releases of QEMU will
> +support machine types from many previous versions.
> +
> +The supported lifetime for versioned machine types is 12 releases,

Maybe rather "The minimum supported lifetime ..." ? In case we decide to
support it longer for any reasons...

 Thomas