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

["Daniel P. Berrange" <berrange@redhat.com>]

On Tue, Jul 04, 2017 at 02:43:29PM +0200, Thomas Huth wrote:
> 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 <berrange@redhat.com>
> > ---
> >  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
> >  
> > +@node Support lifetime
> > +@appendix 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...

FWIW, I explicitly avoided saying "at least" when I wrote this. I
want to make deletion of deprecated features a clearly defined process
where we don't have to re-open the debate of whether its ok to now
delete it. 


> > +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.
> > +
> > +@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.
> 
> Space at wrong location --------------^

Opps.

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

Same point as above - I feel its important to set a clear fixed timeframe
to avoid re-opening debate each time we come to delete something.

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