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