Re: [PATCH] docs/about: Change notes on x86 machine type deprecation into a general one

[Daniel P . Berrangé]

On Thu, Jan 16, 2025 at 09:19:20AM +0000, Daniel P. Berrangé wrote:
> On Thu, Jan 16, 2025 at 09:48:50AM +0100, Philippe Mathieu-Daudé wrote:
> > On 16/1/25 07:46, Thomas Huth wrote:
> > > 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.
> > > 
> > > Signed-off-by: Thomas Huth <thuth@redhat.com>
> > > ---
> > >   docs/about/deprecated.rst       |  7 -------
> > >   docs/about/removed-features.rst | 11 +++++------
> > >   2 files changed, 5 insertions(+), 13 deletions(-)
> > > 
> > > diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> > > index 4a3c302962..7b42d6eecc 100644
> > > --- a/docs/about/deprecated.rst
> > > +++ b/docs/about/deprecated.rst
> > > @@ -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)
> > >   ''''''''''''''''''''''''''''''''''''''''
> > > diff --git a/docs/about/removed-features.rst 
> > > b/docs/about/removed-features.rst
> > > index c6616ce05e..156c0c253c 100644
> > > --- a/docs/about/removed-features.rst
> > > +++ b/docs/about/removed-features.rst
> > > @@ -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
> >     ...
> > 
> > ?
> 
> 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 ?

To answer my own question, yes with something like this:

diff --git a/docs/conf.py b/docs/conf.py
index 31bb9a3789..899ad13305 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -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....


> 
> 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 

> 
> 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
-- 
|: 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 :|