docs/about: Change notes on x86 machine type deprecation into a general one
PATCH 1/1 docs/about: Change notes on x86 machine type deprecation into a general one
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the deprecated.rst file, so we should also have a general note about this in removed-features.rst (which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.
--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)
docs/about/deprecated.rst +0 -7
@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''
docs/about/removed-features.rst +5 -6
@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead. + ``s390-virtio`` (removed in 2.6) ''''''''''''''''''''''''''''''''
@@ -1006,12 +1011,6 @@ mips ``fulong2e`` machine alias (removed in 6.0) This machine has been renamed ``fuloong2e``. -``pc-0.10`` up to ``pc-i440fx-2.3`` (removed in 4.0 up to 9.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These machine types were very old and likely could not be used for live -migration from old QEMU versions anymore. Use a newer machine type instead. - Raspberry Pi ``raspi2`` and ``raspi3`` machines (removed in 6.2) ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Signature · 1 line
2.47.1
Quoted 11 lines · Thomas Huth
Date: Thu, 16 Jan 2025 07:46:44 +0100
From: Thomas Huth <[email protected]>
Subject: [PATCH] docs/about: Change notes on x86 machine type deprecation
into a general oneWe now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.
Quoted 6 lines
Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)
Sounds good to me, so:
Let's see if others have any feedback :-)
Quoted 35 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0
docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 978
Quoted 7 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.
This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...
?
Quoted 17 lines
docs/about/removed-features.rst +1
-6+ ``s390-virtio`` (removed in 2.6) ''''''''''''''''''''''''''''''''@@ -1006,12 +1011,6 @@ mips ``fulong2e`` machine alias (removed in 6.0) This machine has been renamed ``fuloong2e``. -``pc-0.10`` up to ``pc-i440fx-2.3`` (removed in 4.0 up to 9.0) -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These machine types were very old and likely could not be used for live -migration from old QEMU versions anymore. Use a newer machine type instead. - Raspberry Pi ``raspi2`` and ``raspi3`` machines (removed in 6.2) ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
Quoted 59 lines · Philippe Mathieu-Daudé
Quoted 33 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 977
Quoted 6 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...
Quoted 1 line
?
A big part of the reason for the macros for machine type deprecation & then skipping machine registration, was to eliminate repeated manual work that is visible to users if forgotten.
We still have the actual code deletion which is manual, but that's harmless as even if forgotten, such that the code exists, the machine type will have been entirely removed from view.
As such I'm pretty reluctant to suggest we create a new place which needs manually updating when we remove machine types.
I wonder if its possible to get an auto-generated version number into the documentation though ?
eg, so we can have an entry in 'deprecated.rst'
Versioned machine types for x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------
In accordance with our versioned machine type deprecation policy, all machine types older than 7.0.0 have been deprecated.
and in 'removed-features.rst'
Versioned machine types for x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------
In accordance with our versioned machine type removal policy, all machine types older than 4.1.0 have been removed.
where both '7.0.0' and '4.1.0' are variables substituted in by the docs generator in some manner, so we never need touch them manually ?
NB, this auto-deletion logic is currently hacked to only come into effect from 10.1.0 onwards, so we're 1 cycle too early currently (see commit c9fd2d9a48ee3c195cf83cc611b87b09f02f0013)
With 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 70 lines · Daniel P. Berrangé
Quoted 59 lines · Philippe Mathieu-Daudé
Quoted 33 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 977
Quoted 6 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...Quoted 1 line
?
A big part of the reason for the macros for machine type deprecation & then skipping machine registration, was to eliminate repeated manual work that is visible to users if forgotten.
We still have the actual code deletion which is manual, but that's harmless as even if forgotten, such that the code exists, the machine type will have been entirely removed from view.
Quoted 5 lines
As such I'm pretty reluctant to suggest we create a new place which needs manually updating when we remove machine types.
I wonder if its possible to get an auto-generated version number into the documentation though ?
To answer my own question, yes with something like this:
docs/conf.py +28 -1
@@ -110,6 +110,22 @@ else: version = release = "unknown version" +bits = version.split(".") +major = int(bits[0]) +minor = int(bits[1]) +micro = int(bits[2]) + +# Dev snapshot, adjust to next release version +if micro >= 50: + micro = 0 + minor += 1 + if minor == 3: + major += 1 + minor = 0 + +ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro) +ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #
@@ -138,7 +154,18 @@ # environment variable is not set is for the benefit of readthedocs # style document building; our Makefile always sets the variable. confdir = os.getenv('CONFDIR', "/etc/qemu") -rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" + +vars = { + "CONFDIR": confdir, + "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version, + "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version, +} + +rst_epilog = "".join([ + ".. |" + key + "| replace:: ``" + vars[key] + "``\n" + for key in vars.keys() +]) + # We slurp in the defs.rst.inc and literally include it into rst_epilog, # because Sphinx's include:: directive doesn't work with absolute paths # and there isn't any one single relative path that will work for all
Then....
Quoted 8 lines
eg, so we can have an entry in '
deprecated.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type deprecation policy, all machine types older than 7.0.0 have been deprecated.
use |VER_MACHINE_DEPRECATION_VERSION| here
Quoted 8 lines
and in '
removed-features.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type removal policy, all machine types older than 4.1.0 have been removed.
use |VER_MACHINE_DELETION_VERSION| here
though, we should not add to removed-features.rst until 10.1.0 cycle since we don't start to do automatic deletion until then.
With 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 151 lines · Daniel P. Berrangé
Quoted 70 lines · Daniel P. Berrangé
Quoted 59 lines · Philippe Mathieu-Daudé
Quoted 33 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 977
Quoted 6 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...Quoted 1 line
?
A big part of the reason for the macros for machine type deprecation & then skipping machine registration, was to eliminate repeated manual work that is visible to users if forgotten.
We still have the actual code deletion which is manual, but that's harmless as even if forgotten, such that the code exists, the machine type will have been entirely removed from view.
Quoted 5 lines
As such I'm pretty reluctant to suggest we create a new place which needs manually updating when we remove machine types.
I wonder if its possible to get an auto-generated version number into the documentation though ?
To answer my own question, yes with something like this:
docs/conf.py +28
-1@@ -110,6 +110,22 @@ else: version = release = "unknown version" +bits = version.split(".") +major = int(bits[0]) +minor = int(bits[1]) +micro = int(bits[2]) + +# Dev snapshot, adjust to next release version +if micro >= 50: + micro = 0 + minor += 1 + if minor == 3: + major += 1 + minor = 0 + +ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro) +ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #@@ -138,7 +154,18 @@ # environment variable is not set is for the benefit of readthedocs # style document building; our Makefile always sets the variable. confdir = os.getenv('CONFDIR', "/etc/qemu") -rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" + +vars = { + "CONFDIR": confdir, + "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version, + "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version, +} + +rst_epilog = "".join([ + ".. |" + key + "| replace:: ``" + vars[key] + "``\n" + for key in vars.keys() +]) + # We slurp in the defs.rst.inc and literally include it into rst_epilog, # because Sphinx's include:: directive doesn't work with absolute paths # and there isn't any one single relative path that will work for allThen....
Quoted 8 lines
eg, so we can have an entry in '
deprecated.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type deprecation policy, all machine types older than 7.0.0 have been deprecated.
use |VER_MACHINE_DEPRECATION_VERSION| here
Quoted 8 lines
and in '
removed-features.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type removal policy, all machine types older than 4.1.0 have been removed.
Quoted 7 lines
use |VER_MACHINE_DELETION_VERSION| here
though, we should not add to
removed-features.rstuntil 10.1.0 cycle since we don't start to do automatic deletion until then.With regards,
Daniel
It's been quiet. Thomas, wdyt?
Quoted 154 lines · Michael S. Tsirkin
Quoted 153 lines · Daniel P. Berrangé
Quoted 70 lines · Daniel P. Berrangé
Quoted 59 lines · Philippe Mathieu-Daudé
Quoted 33 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 977
Quoted 6 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...Quoted 1 line
?
A big part of the reason for the macros for machine type deprecation & then skipping machine registration, was to eliminate repeated manual work that is visible to users if forgotten.
We still have the actual code deletion which is manual, but that's harmless as even if forgotten, such that the code exists, the machine type will have been entirely removed from view.
Quoted 5 lines
As such I'm pretty reluctant to suggest we create a new place which needs manually updating when we remove machine types.
I wonder if its possible to get an auto-generated version number into the documentation though ?
To answer my own question, yes with something like this:
docs/conf.py +28
-1@@ -110,6 +110,22 @@ else: version = release = "unknown version" +bits = version.split(".") +major = int(bits[0]) +minor = int(bits[1]) +micro = int(bits[2]) + +# Dev snapshot, adjust to next release version +if micro >= 50: + micro = 0 + minor += 1 + if minor == 3: + major += 1 + minor = 0 + +ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro) +ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #@@ -138,7 +154,18 @@ # environment variable is not set is for the benefit of readthedocs # style document building; our Makefile always sets the variable. confdir = os.getenv('CONFDIR', "/etc/qemu") -rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" + +vars = { + "CONFDIR": confdir, + "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version, + "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version, +} + +rst_epilog = "".join([ + ".. |" + key + "| replace:: ``" + vars[key] + "``\n" + for key in vars.keys() +]) + # We slurp in the defs.rst.inc and literally include it into rst_epilog, # because Sphinx's include:: directive doesn't work with absolute paths # and there isn't any one single relative path that will work for allThen....
Quoted 8 lines
eg, so we can have an entry in '
deprecated.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type deprecation policy, all machine types older than 7.0.0 have been deprecated.
use |VER_MACHINE_DEPRECATION_VERSION| here
Quoted 8 lines
and in '
removed-features.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type removal policy, all machine types older than 4.1.0 have been removed.
use |VER_MACHINE_DELETION_VERSION| here
Quoted 7 lines
Quoted 5 lines
though, we should not add to
removed-features.rstuntil 10.1.0 cycle since we don't start to do automatic deletion until then.With regards,
DanielIt's been quiet. Thomas, wdyt?
I assumed Daniel would go forward and post his idea as a proper patch?
Thomas
Quoted 157 lines · Thomas Huth
Quoted 156 lines · Michael S. Tsirkin
Quoted 155 lines · Daniel P. Berrangé
Quoted 70 lines · Daniel P. Berrangé
Quoted 59 lines · Philippe Mathieu-Daudé
Quoted 33 lines · Thomas Huth
We now have a general note about versioned machine types getting deprecated and removed at the beginning of the
deprecated.rstfile, so we should also have a general note about this inremoved-features.rst(which will also apply to versioned non-x86 machine types) instead of listing individual old machine types in the document.Signed-off-by Thomas Huth <[email protected]>--- docs/about/deprecated.rst | 7 ------- docs/about/removed-features.rst | 11 +++++------ 2 files changed, 5 insertions(+), 13 deletions(-)docs/about/deprecated.rst +0
-7@@ -236,13 +236,6 @@ deprecated; use the new name ``dtb-randomness`` instead. The new name better reflects the way this property affects all random data within the device tree blob, not just the ``kaslr-seed`` node. -``pc-i440fx-2.4`` up to ``pc-i440fx-2.12`` (since 9.1) -'''''''''''''''''''''''''''''''''''''''''''''''''''''' - -These old machine types are quite neglected nowadays and thus might have -various pitfalls with regards to live migration. Use a newer machine type -instead. - PPC 405 ``ref405ep`` machine (since 9.1) ''''''''''''''''''''''''''''''''''''''''docs/about/removed-features.rst +0
-0docs/about/removed-features.rst from Linux in 2021, and is not supported anymore by QEMU either. · line 977
Quoted 6 lines
docs/about/removed-features.rst +4
-0@@ -972,6 +972,11 @@ from Linux in 2021, and is not supported anymore by QEMU either. System emulator machines ------------------------ +Note: Versioned machine types that have been introduced in a QEMU version +that has initially been released more than 6 years before are considered +obsolete and will be removed without further notice in this document. +Please use newer machine types instead.This is an improvement. I still wonder if we shouldn't list them removed machines here, to help old users.
Removed in 4.0:
- pc-0.10
- ...
Removed in 9.0:
- pc-i440fx-2.3
Remove in 10.0:
- pc-i440fx-2.4
- pc-i440fx-2.5
- pc-i440fx-2.6
- pc-q35-2.4
- pc-q35-2.5
- pc-q35-2.6
- ARM virt-2.6
...Quoted 1 line
?
A big part of the reason for the macros for machine type deprecation & then skipping machine registration, was to eliminate repeated manual work that is visible to users if forgotten.
We still have the actual code deletion which is manual, but that's harmless as even if forgotten, such that the code exists, the machine type will have been entirely removed from view.
Quoted 5 lines
As such I'm pretty reluctant to suggest we create a new place which needs manually updating when we remove machine types.
I wonder if its possible to get an auto-generated version number into the documentation though ?
To answer my own question, yes with something like this:
docs/conf.py +28
-1@@ -110,6 +110,22 @@ else: version = release = "unknown version" +bits = version.split(".") +major = int(bits[0]) +minor = int(bits[1]) +micro = int(bits[2]) + +# Dev snapshot, adjust to next release version +if micro >= 50: + micro = 0 + minor += 1 + if minor == 3: + major += 1 + minor = 0 + +ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro) +ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #@@ -138,7 +154,18 @@ # environment variable is not set is for the benefit of readthedocs # style document building; our Makefile always sets the variable. confdir = os.getenv('CONFDIR', "/etc/qemu") -rst_epilog = ".. |CONFDIR| replace:: ``" + confdir + "``\n" + +vars = { + "CONFDIR": confdir, + "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version, + "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version, +} + +rst_epilog = "".join([ + ".. |" + key + "| replace:: ``" + vars[key] + "``\n" + for key in vars.keys() +]) + # We slurp in the defs.rst.inc and literally include it into rst_epilog, # because Sphinx's include:: directive doesn't work with absolute paths # and there isn't any one single relative path that will work for allThen....
Quoted 8 lines
eg, so we can have an entry in '
deprecated.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type deprecation policy, all machine types older than 7.0.0 have been deprecated.
use |VER_MACHINE_DEPRECATION_VERSION| here
Quoted 8 lines
and in '
removed-features.rst'Versioned machine types for
x86_64, i386, aarch64 <other targets here>
-----------------------------------------------------------------------In accordance with our versioned machine type removal policy, all machine types older than 4.1.0 have been removed.
use |VER_MACHINE_DELETION_VERSION| here
though, we should not add to
removed-features.rstuntil 10.1.0 cycle since we don't start to do automatic deletion until then.
Quoted 6 lines
Quoted 4 lines
Quoted 2 lines
With regards,
DanielIt's been quiet. Thomas, wdyt?
I assumed Daniel would go forward and post his idea as a proper patch?
I thought I did, but I guess this got lost/forgotten...
With 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 :|