The sentence explaining the deprecation schedule is ambiguous. Make it
clear that a feature deprecated in the Nth release is guaranteed to
remain available in the N+1th release. Removal can occur in the N+2nd
release or later.

As an example of this in action, see commit
25956af3fe5dd0385ad8017bc768a6afe41e2a74 ("block: Finish deprecation of
'qemu-img convert -n -o'"). The feature was deprecated in QEMU 4.2.0. It
was present in the 5.0.0 release and removed in the 5.1.0 release.

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
 docs/system/deprecated.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index 851dbdeb8a..fecfb2f1c1 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -4,9 +4,9 @@ Deprecated features
 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 this section. The feature will remain functional
-for 2 releases prior to actual removal. 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.
+for 1 more release after deprecation. 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.
 
 Prior to the 2.10.0 release there was no official policy on how
 long features would be deprecated prior to their removal, nor
-- 
2.26.2

On Tue, Aug 11, 2020 at 11:47:36AM +0100, Stefan Hajnoczi wrote:
> The sentence explaining the deprecation schedule is ambiguous. Make it
> clear that a feature deprecated in the Nth release is guaranteed to
> remain available in the N+1th release. Removal can occur in the N+2nd
> release or later.
> 
> As an example of this in action, see commit
> 25956af3fe5dd0385ad8017bc768a6afe41e2a74 ("block: Finish deprecation of
> 'qemu-img convert -n -o'"). The feature was deprecated in QEMU 4.2.0. It
> was present in the 5.0.0 release and removed in the 5.1.0 release.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/deprecated.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)

Ping?

> 
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> index 851dbdeb8a..fecfb2f1c1 100644
> --- a/docs/system/deprecated.rst
> +++ b/docs/system/deprecated.rst
> @@ -4,9 +4,9 @@ Deprecated features
>  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 this section. The feature will remain functional
> -for 2 releases prior to actual removal. 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.
> +for 1 more release after deprecation. 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.
>  
>  Prior to the 2.10.0 release there was no official policy on how
>  long features would be deprecated prior to their removal, nor
> -- 
> 2.26.2
> 

On Tue, Aug 11, 2020 at 11:47:36AM +0100, Stefan Hajnoczi wrote:
> The sentence explaining the deprecation schedule is ambiguous. Make it
> clear that a feature deprecated in the Nth release is guaranteed to
> remain available in the N+1th release. Removal can occur in the N+2nd
> release or later.
> 
> As an example of this in action, see commit
> 25956af3fe5dd0385ad8017bc768a6afe41e2a74 ("block: Finish deprecation of
> 'qemu-img convert -n -o'"). The feature was deprecated in QEMU 4.2.0. It
> was present in the 5.0.0 release and removed in the 5.1.0 release.
> 
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
>  docs/system/deprecated.rst | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> index 851dbdeb8a..fecfb2f1c1 100644
> --- a/docs/system/deprecated.rst
> +++ b/docs/system/deprecated.rst
> @@ -4,9 +4,9 @@ Deprecated features
>  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 this section. The feature will remain functional
> -for 2 releases prior to actual removal. 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.
> +for 1 more release after deprecation. 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.

So we're changing

  The feature will remain functional for 2 releases prior to actual removal.

to

  The feature will remain functional for 1 more release after deprecation.

How about

  The feature will remain functional for the release in which it was
  deprecated and one further release. After these two releases, the
  feature is liable to be removed.


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 9/14/20 9:21 AM, Daniel P. Berrangé wrote:
> On Tue, Aug 11, 2020 at 11:47:36AM +0100, Stefan Hajnoczi wrote:
>> The sentence explaining the deprecation schedule is ambiguous. Make it
>> clear that a feature deprecated in the Nth release is guaranteed to
>> remain available in the N+1th release. Removal can occur in the N+2nd
>> release or later.
>>

> So we're changing
> 
>    The feature will remain functional for 2 releases prior to actual removal.
> 
> to
> 
>    The feature will remain functional for 1 more release after deprecation.
> 
> How about
> 
>    The feature will remain functional for the release in which it was
>    deprecated and one further release. After these two releases, the
>    feature is liable to be removed.

Longer, but definitely conveys more information in an 
easier-to-understand format.

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

On Mon, 14 Sep 2020 at 15:22, Daniel P. Berrangé <berrange@redhat.com> wrote:
> So we're changing
>
>   The feature will remain functional for 2 releases prior to actual removal.
>
> to
>
>   The feature will remain functional for 1 more release after deprecation.
>
> How about
>
>   The feature will remain functional for the release in which it was
>   deprecated and one further release. After these two releases, the
>   feature is liable to be removed.

I think the thing which tends to confuse me about the wording
is that it's phrased in terms of "releases", ie point events,
(which is OK for users) but the developers who are adding
deprecation notices and then removing features probably think
more in terms of "release cycles" (ie the periods of time between
the point events), or at least I do, so I have to mentally convert
"functional for two releases" into "so if I deprecate it in this
cycle, then I have to leave the code present in the next cycle
and then am OK to delete the code the cycle after that".
But I don't have any good suggestions for wording, and your proposed
text is definitely clearer I think.

-- PMM

On Mon, Sep 14, 2020 at 03:21:46PM +0100, Daniel P. Berrangé wrote:
> On Tue, Aug 11, 2020 at 11:47:36AM +0100, Stefan Hajnoczi wrote:
> > The sentence explaining the deprecation schedule is ambiguous. Make it
> > clear that a feature deprecated in the Nth release is guaranteed to
> > remain available in the N+1th release. Removal can occur in the N+2nd
> > release or later.
> > 
> > As an example of this in action, see commit
> > 25956af3fe5dd0385ad8017bc768a6afe41e2a74 ("block: Finish deprecation of
> > 'qemu-img convert -n -o'"). The feature was deprecated in QEMU 4.2.0. It
> > was present in the 5.0.0 release and removed in the 5.1.0 release.
> > 
> > Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> > ---
> >  docs/system/deprecated.rst | 6 +++---
> >  1 file changed, 3 insertions(+), 3 deletions(-)
> > 
> > diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
> > index 851dbdeb8a..fecfb2f1c1 100644
> > --- a/docs/system/deprecated.rst
> > +++ b/docs/system/deprecated.rst
> > @@ -4,9 +4,9 @@ Deprecated features
> >  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 this section. The feature will remain functional
> > -for 2 releases prior to actual removal. 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.
> > +for 1 more release after deprecation. 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.
> 
> So we're changing
> 
>   The feature will remain functional for 2 releases prior to actual removal.
> 
> to
> 
>   The feature will remain functional for 1 more release after deprecation.
> 
> How about
> 
>   The feature will remain functional for the release in which it was
>   deprecated and one further release. After these two releases, the
>   feature is liable to be removed.

Nice, that is clearer. I have send a v2.

Stefan