On Thu, Feb 20, 2025 at 04:21:42PM +0100, Thomas Huth wrote:
> On 20/02/2025 15.59, Michael S. Tsirkin wrote:
> > On Thu, Jan 16, 2025 at 10:59:10AM +0000, Daniel P. Berrangé wrote:
> > > 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 <th...@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
> >
> > It'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
--
|: 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 :|
