* [PATCH] docs/system: clarify deprecation scheduled
@ 2020-08-11 10:47 Stefan Hajnoczi
2020-09-14 13:46 ` Stefan Hajnoczi
2020-09-14 14:21 ` Daniel P. Berrangé
0 siblings, 2 replies; 6+ messages in thread
From: Stefan Hajnoczi @ 2020-08-11 10:47 UTC (permalink / raw)
To: qemu-devel
Cc: libvir-list, philmd, Daniel Berrange, Stefan Hajnoczi,
Peter Maydell
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
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH] docs/system: clarify deprecation scheduled
2020-08-11 10:47 [PATCH] docs/system: clarify deprecation scheduled Stefan Hajnoczi
@ 2020-09-14 13:46 ` Stefan Hajnoczi
2020-09-14 14:21 ` Daniel P. Berrangé
1 sibling, 0 replies; 6+ messages in thread
From: Stefan Hajnoczi @ 2020-09-14 13:46 UTC (permalink / raw)
To: qemu-devel; +Cc: libvir-list, philmd, Daniel Berrange, Peter Maydell
[-- Attachment #1: Type: text/plain, Size: 1793 bytes --]
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
>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH] docs/system: clarify deprecation scheduled
2020-08-11 10:47 [PATCH] docs/system: clarify deprecation scheduled Stefan Hajnoczi
2020-09-14 13:46 ` Stefan Hajnoczi
@ 2020-09-14 14:21 ` Daniel P. Berrangé
2020-09-14 14:32 ` Eric Blake
` (2 more replies)
1 sibling, 3 replies; 6+ messages in thread
From: Daniel P. Berrangé @ 2020-09-14 14:21 UTC (permalink / raw)
To: Stefan Hajnoczi; +Cc: libvir-list, Peter Maydell, philmd, qemu-devel
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 :|
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH] docs/system: clarify deprecation scheduled
2020-09-14 14:21 ` Daniel P. Berrangé
@ 2020-09-14 14:32 ` Eric Blake
2020-09-14 14:35 ` Peter Maydell
2020-09-15 15:10 ` Stefan Hajnoczi
2 siblings, 0 replies; 6+ messages in thread
From: Eric Blake @ 2020-09-14 14:32 UTC (permalink / raw)
To: Daniel P. Berrangé, Stefan Hajnoczi
Cc: libvir-list, Peter Maydell, philmd, qemu-devel
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs/system: clarify deprecation scheduled
2020-09-14 14:21 ` Daniel P. Berrangé
2020-09-14 14:32 ` Eric Blake
@ 2020-09-14 14:35 ` Peter Maydell
2020-09-15 15:10 ` Stefan Hajnoczi
2 siblings, 0 replies; 6+ messages in thread
From: Peter Maydell @ 2020-09-14 14:35 UTC (permalink / raw)
To: Daniel P. Berrangé
Cc: Libvirt, Philippe Mathieu-Daudé, QEMU Developers,
Stefan Hajnoczi
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] docs/system: clarify deprecation scheduled
2020-09-14 14:21 ` Daniel P. Berrangé
2020-09-14 14:32 ` Eric Blake
2020-09-14 14:35 ` Peter Maydell
@ 2020-09-15 15:10 ` Stefan Hajnoczi
2 siblings, 0 replies; 6+ messages in thread
From: Stefan Hajnoczi @ 2020-09-15 15:10 UTC (permalink / raw)
To: Daniel P. Berrangé; +Cc: libvir-list, Peter Maydell, philmd, qemu-devel
[-- Attachment #1: Type: text/plain, Size: 2208 bytes --]
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
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-09-15 15:14 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-08-11 10:47 [PATCH] docs/system: clarify deprecation scheduled Stefan Hajnoczi
2020-09-14 13:46 ` Stefan Hajnoczi
2020-09-14 14:21 ` Daniel P. Berrangé
2020-09-14 14:32 ` Eric Blake
2020-09-14 14:35 ` Peter Maydell
2020-09-15 15:10 ` Stefan Hajnoczi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).