Skip to contentSkip to conversation

docs/system: clarify deprecation scheduled

PATCH Superseded Stefan Hajnoczi 4 participants 6 messages Aug 11, 2020 – Sep 15, 2020

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

---
 docs/system/deprecated.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/system/deprecated.rst +3 -3
index 851dbdeb8a..fecfb2f1c1 100644
@@ -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
Signature · 1 line
2.26.2
#1 lore raw
Quoted 20 lines · Stefan Hajnoczi

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.

---
 docs/system/deprecated.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/system/deprecated.rst +0 -0
index 851dbdeb8a..fecfb2f1c1 100644

docs/system/deprecated.rst Deprecated features · line 9

Quoted 9 lines
docs/system/deprecated.rst +3 -3
@@ -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

Signature · 3 lines
|: 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 :|
#2 lore raw
Quoted 13 lines · Daniel P. Berrangé
Quoted 5 lines · Stefan Hajnoczi

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

Quoted 7 lines

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.

Signature · 3 lines
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org
#3 lore raw
In reply to Daniel P. Berrangé
Quoted 6 lines · Daniel P. Berrangé

So we're changing

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

to

Quoted 7 lines

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

#4 lore raw
In reply to Daniel P. Berrangé
Quoted 37 lines · Daniel P. Berrangé
Quoted 20 lines · Stefan Hajnoczi

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.

---
 docs/system/deprecated.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
docs/system/deprecated.rst +0 -0
index 851dbdeb8a..fecfb2f1c1 100644

docs/system/deprecated.rst Deprecated features · line 9

Quoted 9 lines
docs/system/deprecated.rst +3 -3
@@ -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

Quoted 7 lines

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

#5 lore raw
In reply to Stefan Hajnoczi
Quoted 10 lines · Stefan Hajnoczi

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.

Quoted 4 lines
---
 docs/system/deprecated.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

Ping?

Quoted 21 lines
docs/system/deprecated.rst +3 -3
index 851dbdeb8a..fecfb2f1c1 100644
@@ -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
Signature · 1 line
2.26.2