docs/system: clarify deprecation scheduled
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
@@ -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
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.Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/system/deprecated.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)docs/system/deprecated.rst +0
-0
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 :|
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
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
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.Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/system/deprecated.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)docs/system/deprecated.rst +0
-0docs/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
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
Signed-off-by Stefan Hajnoczi <[email protected]>--- docs/system/deprecated.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
Ping?
Quoted 21 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. Prior to the 2.10.0 release there was no official policy on how long features would be deprecated prior to their removal, norSignature · 1 line
2.26.2