[Qemu-devel] [PATCH v2 0/2] Document deprecated features & support lifecycle

[Qemu-devel] [PATCH v2 0/2] Document deprecated features & support lifecycle

[Daniel P. Berrange]

This is a followup to

  v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html

The goal is to clarify to users & app developers what they can expect
from QEMU in terms of feature lifecycle & any deprecation policy should
it be neccessary to remove features.

Changed in v2:

 - Split into 2 patches so we can consider each suggested addition
   independantly.

Daniel P. Berrange (2):
  docs: document deprecated features in appendix
  docs: document support lifetime for features

 qemu-doc.texi | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

-- 
2.9.3

[Qemu-devel] [PATCH v2 1/2] docs: document deprecated features in appendix

[Daniel P. Berrange]

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. This adds an appendix to the doc that records
when each deprecation[1] was made and provides text explaining
what to use instead.

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 | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/qemu-doc.texi b/qemu-doc.texi
index 965ba59..29f89d8 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -37,6 +37,7 @@
 * QEMU Guest Agent::
 * QEMU User space emulator::
 * Implementation notes::
+* Deprecations::
 * License::
 * Index::
 @end menu
@@ -3016,6 +3017,19 @@ Run the emulation in single step mode.
 
 @include qemu-tech.texi
 
+@node Deprecations
+@appendix Deprecations
+
+The following is a list of features which have been marked as deprecated,
+pending removal in a future release:
+
+@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

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

[Daniel P. Berrange]

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 <berrange@redhat.com>
---
 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
 
+@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
+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.
+
+@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
 
-- 
2.9.3

Re: [Qemu-devel] [PATCH v2 0/2] Document deprecated features & support lifecycle

[Stefan Hajnoczi]

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

On Tue, Jun 06, 2017 at 12:05:54PM +0100, Daniel P. Berrange wrote:
> This is a followup to
> 
>   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
> 
> The goal is to clarify to users & app developers what they can expect
> from QEMU in terms of feature lifecycle & any deprecation policy should
> it be neccessary to remove features.
> 
> Changed in v2:
> 
>  - Split into 2 patches so we can consider each suggested addition
>    independantly.
> 
> Daniel P. Berrange (2):
>   docs: document deprecated features in appendix
>   docs: document support lifetime for features
> 
>  qemu-doc.texi | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 48 insertions(+)
> 
> -- 
> 2.9.3
> 

Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>

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

Re: [Qemu-devel] [PATCH v2 1/2] docs: document deprecated features in appendix

[Markus Armbruster]

"Daniel P. Berrange" <berrange@redhat.com> writes:

> 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. This adds an appendix to the doc that records
> when each deprecation[1] was made and provides text explaining
> what to use instead.
>
> 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.

As written, this is PATCH RFC.  We can either collect the currently
deprecated features before we commit (with the footnote dropped), or
collect later (but then we should note the incompleteness in
qemu-doc.texi, not just the commit message).

> ---
>  qemu-doc.texi | 14 ++++++++++++++
>  1 file changed, 14 insertions(+)
>
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 965ba59..29f89d8 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -37,6 +37,7 @@
>  * QEMU Guest Agent::
>  * QEMU User space emulator::
>  * Implementation notes::
> +* Deprecations::
>  * License::
>  * Index::
>  @end menu
> @@ -3016,6 +3017,19 @@ Run the emulation in single step mode.
>  
>  @include qemu-tech.texi
>  
> +@node Deprecations

Perhaps "Deprecated Features"?  Not a native speaker...

> +@appendix Deprecations
> +
> +The following is a list of features which have been marked as deprecated,
> +pending removal in a future release:
> +
> +@section -drive boot=on|off (since v1.3.0)
> +Since release 1.3.0, the ``boot=on|off'' parameter to ``-drive''

I wouldn't repeat "since v1.3.0".  It'll get old quickly when the list
grows.

> +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

I like it.

Of course, new deprecations need to be in release notes, too.  If the
duplication bothers us, we could perhaps just point to release notes.
We'd have to check and amend old release notes to make sure all
currently deprecated features are covered.

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

[Markus Armbruster]

"Daniel P. Berrange" <berrange@redhat.com> 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 <berrange@redhat.com>
> ---
>  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
>  
> +@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
> +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.
> +
> +@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

"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

Re: [Qemu-devel] [PATCH v2 1/2] docs: document deprecated features in appendix

[Daniel P. Berrange]

On Fri, Jun 23, 2017 at 01:44:46PM +0200, Markus Armbruster wrote:
> "Daniel P. Berrange" <berrange@redhat.com> writes:
> 
> > 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. This adds an appendix to the doc that records
> > when each deprecation[1] was made and provides text explaining
> > what to use instead.
> >
> > 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.
> 
> As written, this is PATCH RFC.  We can either collect the currently
> deprecated features before we commit (with the footnote dropped), or
> collect later (but then we should note the incompleteness in
> qemu-doc.texi, not just the commit message).

Assuming this patches continues to get favourable feedback, my
intention was/is to grep the source code for the word "deprecated"
to identify the "full" set, and then send a non-RFC version.


> > @@ -3016,6 +3017,19 @@ Run the emulation in single step mode.
> >  
> >  @include qemu-tech.texi
> >  
> > +@node Deprecations
> 
> Perhaps "Deprecated Features"?  Not a native speaker...

Yep, sounds better.

> 
> > +@appendix Deprecations
> > +
> > +The following is a list of features which have been marked as deprecated,
> > +pending removal in a future release:
> > +
> > +@section -drive boot=on|off (since v1.3.0)
> > +Since release 1.3.0, the ``boot=on|off'' parameter to ``-drive''
> 
> I wouldn't repeat "since v1.3.0".  It'll get old quickly when the list
> grows.

Agreed.

> 
> > +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
> 
> I like it.
> 
> Of course, new deprecations need to be in release notes, too.  If the
> duplication bothers us, we could perhaps just point to release notes.
> We'd have to check and amend old release notes to make sure all
> currently deprecated features are covered.

Since the texi is fairly well structured, we could extract the list
of new deprecations from this doc in an automated manner, to populate
the per-release notes.  I'd like to keep the combined list as the
canonical location of the info, so app developers have a single
place to look to find the list, rather than searching multiple
release notes.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Daniel P. Berrange]

On Fri, Jun 23, 2017 at 01:48:34PM +0200, Markus Armbruster wrote:
> "Daniel P. Berrange" <berrange@redhat.com> 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 <berrange@redhat.com>
> > ---
> >  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
> >  
> > +@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
> > +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.
> > +
> > +@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
> 
> "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?

FWIW, this was a fairly arbitrary time frame I picked, to stimulate
discussion. 4 years is long time for community supported distros, but
for enterprise distros like RHEL, where there's a long gap between
major versions, 4 years is probably close to the minimum practical
to enable upgrades. eg RHEL7.0 shipped 1.5.3 version (date 2013/08)
wanted to enable machine type compat with RHEL6's 0.12 version
(date 2009/12).

The flip side though is that enterprise distros don't typically use
the machine types "as is", then define custom downstream only versions.
They just need the underlying features to still exist.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|

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

[Peter Maydell]

On 23 June 2017 at 12:48, Markus Armbruster <armbru@redhat.com> wrote:
> "Daniel P. Berrange" <berrange@redhat.com> writes:
>> +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?

I don't have an opinion personally because I don't care
about backcompat for what I use QEMU for. From a pure
upstream perspective, given that we don't support anything
beyond the previous stable branch for security fixes we
already don't really expect people to be doing production
work on old upstream releases. So this is a distro
question really and we need input from the people who
package QEMU. Given that for instance Ubuntu LTSes get
5 years of support I would guess that 4 years might be
a little low, but really we should ask the people with
a more informed opinion.

thanks
-- PMM