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

[Eduardo Habkost]

On Fri, Jul 14, 2017 at 11:15:48AM +0100, 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.
> 
> 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 48af5155c7..f067015d4b 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
> @@ -3128,6 +3129,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.

Is a "major release" a x.0 release?  So if we decide to to
deprecate a feature in QEMU 2.10, does this mean we will be able
to remove it only on QEMU 4.0?

This doesn't sound like a predictable feature lifetime, if we
don't have a predictable policy for major release numbering.

> +
> +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.
> +
> +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,
> +which is equivalent to 4 years worth of previous QEMU releases.
> +
>  @node License
>  @appendix License
>  
> -- 
> 2.13.0
> 

-- 
Eduardo