Re: [Qemu-devel] [PATCH RFC] docs: document support lifetime and deprecation policy

[Stefan Hajnoczi <stefanha@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 3830 bytes --]

On Wed, May 10, 2017 at 12:15:35PM +0100, Daniel P. Berrange wrote:
> The deprecation of features in QEMU is totally adhoc currently,
> with no way for the user to get a list of what is deprecated
> in each release. There is also no guidance on the duration of
> support for features such as versioned machine types, which
> have a finite useful life.
> 
> This adds two new appendix entries to the main QEMU documentation.
> The first appendix lists items which have finite lifecycles,
> and sets out the policy that is used for deprecating & removing
> features which have indefinite lifecycles. The second appendix
> provides a list of all[1] currently deprecated features, along
> with the release they were deprecated in.
> 
> Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
> 
> [1] This is a lie. I've only listed one deprecated feature. Once
>     we agree on the general concept, we can fill out the doc
>     with the rest of the currently deprecated features.
> ---
>  qemu-doc.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 47 insertions(+)

Peter maydell is away in May.  He usually participates in discussions on
this topic.  Unless there are urgent issues I suggest we wait until June
to commit QEMU to new policies.

> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 794ab4a..899808b 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -36,6 +36,8 @@
>  * QEMU System emulator for non PC targets::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Support lifetime::
> +* Deprecations::
>  * License::
>  * Index::
>  @end menu
> @@ -2996,6 +2998,51 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> +@node Support lifetime
> +@appendix 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
> +a warning if used when QEMU starts up/
> +
> +Certain features will have an inherently finite lifetime, and thus
> +will be removed on a fixed schedule.
> +
> +@node Machine types
> +@section 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 machine types is 12 releases, which is
> +equivalent to 4 years worth of previous QEMU releases.
> +
> +@node Deprecations
> +@appendix Deprecations
> +
> +The following is a list of features which have been marked as deprecated,
> +pending removal in a future list:
> +
> +@section -drive boot=on|off (since v1.3.0)
> +Since release 1.3.0, the ``boot=on|off'' parameter to ``-drive''
> +is no longer honoured. It is currently ignored, but a future verson
> +will reject this parameter with an error. Applications should use
> +the ``bootindex=N'' parameter to set an absolute ordering between
> +devices instead.
> +
>  @node License
>  @appendix License
>  
> -- 
> 2.9.3
> 
> 

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 455 bytes --]