This is a followup to

  v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
  v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.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.

The list of features marked as deprecated was determined by looking at
the QEMU source for the word "deprecated'. It was then compared with
the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval

Key differences with the wiki page that Thomas wrote up vs patch 2
in this series

 - Deprecated features are given a fixed lifespan of 2 releases,
   rather than listing deletion at a future "major" v3.0.0 release. 
   This ensures that applications like libvirt have a predictable 
   fixed amount of time to react to deprecations.

 - Only lists features which are currently officially deprecated,
   no list of possible future candidates. The wiki page is probably
   a good place to maintain a list of future possible deprecations.
   To turn them into actual deprecations, a patch to the QEMU doc
   can then be posted & reviewed in the normal manner.

 - Not listing the '-6' and '-e' args to qemu-img create. Those
   were never deprecations, because the functionality was
   immediately turned into a fatal error. I sent a patch to
   just delete them straight away, as they've been unconditionlly
   broken for 7 years now which is enough :-) 

    https://lists.gnu.org/archive/html/qemu-devel/2017-07/msg00616.html

Changed in v3:

 - Rename appendix to "Deprecated features" (Markus)
 - List all currently deprecated features
 - Document that deprecated features will be removed after
   2 releases of being deprecated
 - Clarify that clock for removing historically deprecated
   features starts with the forthcoming release.

Changed in v2:

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

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

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

-- 
2.9.4

On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
> This is a followup to
>
>   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
>   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.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.
>
> The list of features marked as deprecated was determined by looking at
> the QEMU source for the word "deprecated'. It was then compared with
> the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
>
> Key differences with the wiki page that Thomas wrote up vs patch 2
> in this series
>
>  - Deprecated features are given a fixed lifespan of 2 releases,
>    rather than listing deletion at a future "major" v3.0.0 release.
>    This ensures that applications like libvirt have a predictable
>    fixed amount of time to react to deprecations.

That's 8 months. Is that enough time for QEMU versions to get into
distros and out to users? (I don't necessarily think it's too short,
but it seems worth thinking about.)

thanks
-- PMM

On Tue, Jul 04, 2017 at 01:00:54PM +0100, Peter Maydell wrote:
> On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
> > This is a followup to
> >
> >   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
> >   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.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.
> >
> > The list of features marked as deprecated was determined by looking at
> > the QEMU source for the word "deprecated'. It was then compared with
> > the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
> >
> > Key differences with the wiki page that Thomas wrote up vs patch 2
> > in this series
> >
> >  - Deprecated features are given a fixed lifespan of 2 releases,
> >    rather than listing deletion at a future "major" v3.0.0 release.
> >    This ensures that applications like libvirt have a predictable
> >    fixed amount of time to react to deprecations.
> 
> That's 8 months. Is that enough time for QEMU versions to get into
> distros and out to users? (I don't necessarily think it's too short,
> but it seems worth thinking about.)

If someone is consuming QEMU via a distro that releases every 6 months
(eg Fedora/Ubuntu), then by the time they see the deprcation message
there may not be much time left before feature deletion. On the flipside
they will not be suspectible to the feature deletion, until the next
major release of their distro, another 6 months after that. This does,
however, not provide much time for them to object to feature removal
to try to convince us to un-deprecate the feature.

If someone is consuming QEMU directly from upstream, it is hard to
answer, because they might rebase to newer QEMU frequently, or they
may stick on a release forever. People in the latter group though
would have a very long time before being impacted by any delation,
while people in the former group would see the deprecation reasonably
early.

If we publicise the deprecations in release notes, that gives a more
visible heads up to people than we've ever had in the past. So even
if they're not consuming new QEMU releases any time soon, they still
stand a chance of hearing about the planned feature removal and
planning ahead.

From libvirt POV, we track QEMU activity quite closely and release
libvirt once a month, so that leaves libvirt developers 8 releases
in which to get a fix done to stop using the deprecated feature,
so I think that's acceptable for libvirt.


I think 2 releases is the minimum acceptable window of deprecation,
but I also wouldn't object if we wanted to make it 3 release, so
there's a nice clear "1 year" grace period before deletion. That
would make it slightly more likely that users of distros would
see the warning before the feature has actually been deleted.

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

On 04.07.2017 14:16, Daniel P. Berrange wrote:
> On Tue, Jul 04, 2017 at 01:00:54PM +0100, Peter Maydell wrote:
>> On 4 July 2017 at 12:14, Daniel P. Berrange <berrange@redhat.com> wrote:
>>> This is a followup to
>>>
>>>   v1: https://lists.gnu.org/archive/html/qemu-devel/2017-05/msg02390.html
>>>   v2: https://lists.gnu.org/archive/html/qemu-devel/2017-06/msg01286.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.
>>>
>>> The list of features marked as deprecated was determined by looking at
>>> the QEMU source for the word "deprecated'. It was then compared with
>>> the doc Thomas put up at http://wiki.qemu.org/Features/LegacyRemoval
>>>
>>> Key differences with the wiki page that Thomas wrote up vs patch 2
>>> in this series
>>>
>>>  - Deprecated features are given a fixed lifespan of 2 releases,
>>>    rather than listing deletion at a future "major" v3.0.0 release.
>>>    This ensures that applications like libvirt have a predictable
>>>    fixed amount of time to react to deprecations.
>>
>> That's 8 months. Is that enough time for QEMU versions to get into
>> distros and out to users? (I don't necessarily think it's too short,
>> but it seems worth thinking about.)
[...]
> I think 2 releases is the minimum acceptable window of deprecation,
> but I also wouldn't object if we wanted to make it 3 release, so
> there's a nice clear "1 year" grace period before deletion. That
> would make it slightly more likely that users of distros would
> see the warning before the feature has actually been deleted.

Last time we discussed this, nobody insisted on 3 releases, so I think
we should start with 2 releases. If somebody complains later that this
is too short, we can still bump it to 3 releases instead.

 Thomas

On 04.07.2017 13:14, Daniel P. Berrange wrote:
[...]
>  - Not listing the '-6' and '-e' args to qemu-img create. Those
>    were never deprecations, because the functionality was
>    immediately turned into a fatal error.
How did you come to that conclusion? As far as I can see, the -6 option
has been added by commit ec36ba14748e140dda2 and that was part of QEMU
v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
part of QEMU v0.14.

 Thomas

On Tue, Jul 04, 2017 at 02:21:28PM +0200, Thomas Huth wrote:
> On 04.07.2017 13:14, Daniel P. Berrange wrote:
> [...]
> >  - Not listing the '-6' and '-e' args to qemu-img create. Those
> >    were never deprecations, because the functionality was
> >    immediately turned into a fatal error.
> How did you come to that conclusion? As far as I can see, the -6 option
> has been added by commit ec36ba14748e140dda2 and that was part of QEMU
> v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
> part of QEMU v0.14.

A 'deprecation' message implies that the functionality continues to
work, but the user gets a warning that its going away. In this case
the user gets a warning, and the functionality is unusable - qemu-img
just exits immediately. This isn't deprecation in any normal sense,
it is just immediate feature removal with an message telling you it
has already been deleted :-(

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

On 04.07.2017 14:27, Daniel P. Berrange wrote:
> On Tue, Jul 04, 2017 at 02:21:28PM +0200, Thomas Huth wrote:
>> On 04.07.2017 13:14, Daniel P. Berrange wrote:
>> [...]
>>>  - Not listing the '-6' and '-e' args to qemu-img create. Those
>>>    were never deprecations, because the functionality was
>>>    immediately turned into a fatal error.
>> How did you come to that conclusion? As far as I can see, the -6 option
>> has been added by commit ec36ba14748e140dda2 and that was part of QEMU
>> v0.10. The deprecation was done in commit eec77d9e712bd415 and that was
>> part of QEMU v0.14.
> 
> A 'deprecation' message implies that the functionality continues to
> work, but the user gets a warning that its going away. In this case
> the user gets a warning, and the functionality is unusable - qemu-img
> just exits immediately. This isn't deprecation in any normal sense,
> it is just immediate feature removal with an message telling you it
> has already been deleted :-(

Ah, right, of course ... I somehow read your original sentence that the
functionality would have been added in one release cycle and also
removed again in the same cycle, that's why I was confused, but it makes
sense now. So yes, should be fine to remove this code immediately now.

 Thomas