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

[Thomas Huth <thuth@redhat.com>]

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 <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
> 
> It's been quiet. Thomas, wdyt?

I assumed Daniel would go forward and post his idea as a proper patch?

  Thomas