We deprecate versioned machine types on a fixed schedule. This allows us
to auto-generate a paragraph in the deprecated.rst document that always
has accurate version info.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/about/deprecated.rst |  7 +++++++
 docs/conf.py              | 33 ++++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
index abadf8de27..da2b1b48ca 100644
--- a/docs/about/deprecated.rst
+++ b/docs/about/deprecated.rst
@@ -269,6 +269,13 @@ Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead.
 System emulator machines
 ------------------------
 
+Versioned machine types (aarch64, arm, i386, m68k, ppc, ppc64, s390x, x86_64)
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+In accordance with our versioned machine type deprecation policy, all machine
+types with version |VER_MACHINE_DEPRECATION_VERSION|, or older, have been
+deprecated.
+
 Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1)
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
diff --git a/docs/conf.py b/docs/conf.py
index 31bb9a3789..421ece1024 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -110,6 +110,27 @@
     else:
         version = release = "unknown version"
 
+bits = version.split(".")
+
+major = int(bits[0])
+minor = int(bits[1])
+micro = int(bits[2])
+
+# Check for a dev snapshot, so we can adjust to next
+# predicted release version.
+#
+# This assumes we do 3 releases per year, so must bump
+# major if minor == 2
+if micro >= 50:
+    micro = 0
+    if minor == 2:
+        major += 1
+        minor = 0
+    else:
+        minor += 1
+
+ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro)
+
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -138,7 +159,17 @@
 # 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,
+}
+
+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
-- 
2.47.1

On 25/02/2025 21.04, Daniel P. Berrangé wrote:
> We deprecate versioned machine types on a fixed schedule. This allows us
> to auto-generate a paragraph in the deprecated.rst document that always
> has accurate version info.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   docs/about/deprecated.rst |  7 +++++++
>   docs/conf.py              | 33 ++++++++++++++++++++++++++++++++-
>   2 files changed, 39 insertions(+), 1 deletion(-)
> 
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index abadf8de27..da2b1b48ca 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -269,6 +269,13 @@ Use ``Sun-UltraSparc-IIIi-plus`` and ``Sun-UltraSparc-IV-plus`` instead.
>   System emulator machines
>   ------------------------
>   
> +Versioned machine types (aarch64, arm, i386, m68k, ppc, ppc64, s390x, x86_64)
> +'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
> +
> +In accordance with our versioned machine type deprecation policy, all machine
> +types with version |VER_MACHINE_DEPRECATION_VERSION|, or older, have been
> +deprecated.
> +
>   Arm ``virt`` machine ``dtb-kaslr-seed`` property (since 7.1)
>   ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
>   
> diff --git a/docs/conf.py b/docs/conf.py
> index 31bb9a3789..421ece1024 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -110,6 +110,27 @@
>       else:
>           version = release = "unknown version"
>   
> +bits = version.split(".")
> +
> +major = int(bits[0])
> +minor = int(bits[1])
> +micro = int(bits[2])
> +
> +# Check for a dev snapshot, so we can adjust to next
> +# predicted release version.
> +#
> +# This assumes we do 3 releases per year, so must bump
> +# major if minor == 2
> +if micro >= 50:
> +    micro = 0
> +    if minor == 2:
> +        major += 1
> +        minor = 0
> +    else:
> +        minor += 1
> +
> +ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro)

While the prediction should work fine for major and minor numbers, I think 
this will look weird for the micro numbers in stable releases. E.g. if we 
release 10.1.9 one day, the ver_machine_deprecation_version will be set to 
7.1.9 - which never existed. I think it would be better to always use micro 
= 0 here instead.

  Thomas