Re: [PATCH] docs/system: clarify deprecation scheduled

[Daniel P . Berrangé]

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