[PATCH] docs/system: clarify deprecation scheduled
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
participants (4)
-
Daniel P. Berrangé -
Eric Blake -
Peter Maydell -
Stefan Hajnoczi