[PATCH 0/4] docs: automated info about machine deprecation/removal info

[PATCH 0/4] docs: automated info about machine deprecation/removal info

[Daniel P. Berrangé]

Since we deprecate and remove versioned machine types on a fixed
schedule, we can automatically ensure that the docs reflect the
latest version info, rather than requiring manual updates on each
dev cycle.

The first patch in this series fixes the logic to ensure dev snapshots
and release candidates don't have an off-by-1 error in setting
deprecation and removal thresholds - they must predict the next formal
release version number.

The remaining patches deal with the docs stuff.

The first two patches can be applied in this release (10.0) if desired.

The third patch documents deletion logic that doesn't come into effect
until the 10.1.0 release is out, so we shouldn't include that commit
in 10.0.0. It can be applied after the following is reverted:

  commit c9fd2d9a48ee3c195cf83cc611b87b09f02f0013
  Author: Daniel P. Berrangé <berrange@redhat.com>
  Date:   Thu Jun 20 17:57:37 2024 +0100

    include/hw: temporarily disable deletion of versioned machine types

    The new deprecation and deletion policy for versioned machine types is
    being introduced in QEMU 9.1.0.

    Under the new policy a number of old machine types (any prior to 2.12)
    would be liable for immediate deletion which would be a violation of our
    historical deprecation and removal policy

    Thus automatic deletions (by skipping QOM registration) are temporarily
    gated on existance of the env variable "QEMU_DELETE_MACHINES" / QEMU
    version number >= 10.1.0. This allows opt-in testing of the automatic
    deletion logic, while activating it fully in QEMU >= 10.1.0.

    This whole commit should be reverted in the 10.1.0 dev cycle or shortly
    thereafter.

Daniel P. Berrangé (4):
  include/hw/boards: cope with dev/rc versions in deprecation checks
  docs/about/deprecated: auto-generate a note for versioned machine
    types
  docs/about/removed-features: auto-generate a note for versioned
    machine types
  include/hw/boards: add warning about changing deprecation logic

 docs/about/deprecated.rst       |  7 ++++++
 docs/about/removed-features.rst | 10 +++++----
 docs/conf.py                    | 39 ++++++++++++++++++++++++++++++++-
 include/hw/boards.h             | 39 +++++++++++++++++++++++++++++++--
 4 files changed, 88 insertions(+), 7 deletions(-)

-- 
2.47.1

[PATCH 1/4] include/hw/boards: cope with dev/rc versions in deprecation checks

[Daniel P. Berrangé]

When VERSION is set to a development snapshot (micro >= 50), or a release
candidate (micro >= 90) we have an off-by-1 in determining deprecation
and deletion thresholds for versioned machine types. In such cases we need
to use the next major/minor version in threshold checks.

This adapts the deprecation macros to do "next version" prediction when
seeing a dev/rc version number.

This ensures users of release candidates get an accurate view of machines
that will be deprecated/deleted in the final release.

This requires hardcoding our current release policy of 3 releases per
year, with a major bump at the start of each year, and that dev/rc
versions have micro >= 50.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 include/hw/boards.h | 33 ++++++++++++++++++++++++++++++++-
 1 file changed, 32 insertions(+), 1 deletion(-)

diff --git a/include/hw/boards.h b/include/hw/boards.h
index 9360d1ce39..dcfb251cbd 100644
--- a/include/hw/boards.h
+++ b/include/hw/boards.h
@@ -647,11 +647,42 @@ struct MachineState {
     " years old are subject to deletion after " \
     stringify(MACHINE_VER_DELETION_MAJOR) " years"
 
-#define _MACHINE_VER_IS_EXPIRED_IMPL(cutoff, major, minor) \
+#define _MACHINE_VER_IS_CURRENT_EXPIRED(cutoff, major, minor) \
     (((QEMU_VERSION_MAJOR - major) > cutoff) || \
      (((QEMU_VERSION_MAJOR - major) == cutoff) && \
       (QEMU_VERSION_MINOR - minor) >= 0))
 
+#define _MACHINE_VER_IS_NEXT_MINOR_EXPIRED(cutoff, major, minor) \
+    (((QEMU_VERSION_MAJOR - major) > cutoff) || \
+     (((QEMU_VERSION_MAJOR - major) == cutoff) && \
+      ((QEMU_VERSION_MINOR + 1) - minor) >= 0))
+
+#define _MACHINE_VER_IS_NEXT_MAJOR_EXPIRED(cutoff, major, minor) \
+    ((((QEMU_VERSION_MAJOR + 1) - major) > cutoff) ||            \
+     ((((QEMU_VERSION_MAJOR + 1) - major) == cutoff) &&          \
+      (0 - minor) >= 0))
+
+/*
+ * - The first check applies to formal releases
+ * - The second check applies to dev snapshots / release candidates
+ *   where the next major version is the same.
+ *   e.g. 9.0.50, 9.1.50, 9.0.90, 9.1.90
+ * - The third check applies to dev snapshots / release candidates
+ *   where the next major version will change.
+ *   e.g. 9.2.50, 9.2.90
+ *
+ * NB: this assumes we do 3 minor releases per year, before bumping major,
+ * and dev snapshots / release candidates are numbered with micro >= 50
+ * If this ever changes the logic below will need modifying....
+ */
+#define _MACHINE_VER_IS_EXPIRED_IMPL(cutoff, major, minor) \
+    ((QEMU_VERSION_MICRO < 50 && \
+      _MACHINE_VER_IS_CURRENT_EXPIRED(cutoff, major, minor)) || \
+     (QEMU_VERSION_MICRO >= 50 && QEMU_VERSION_MINOR < 2 && \
+      _MACHINE_VER_IS_NEXT_MINOR_EXPIRED(cutoff, major, minor)) || \
+     (QEMU_VERSION_MICRO >= 50 && QEMU_VERSION_MINOR == 2 && \
+      _MACHINE_VER_IS_NEXT_MAJOR_EXPIRED(cutoff, major, minor)))
+
 #define _MACHINE_VER_IS_EXPIRED2(cutoff, major, minor) \
     _MACHINE_VER_IS_EXPIRED_IMPL(cutoff, major, minor)
 #define _MACHINE_VER_IS_EXPIRED3(cutoff, major, minor, micro) \
-- 
2.47.1

[PATCH 2/4] docs/about/deprecated: auto-generate a note for versioned machine types

[Daniel P. Berrangé]

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

Re: [PATCH 2/4] docs/about/deprecated: auto-generate a note for versioned machine types

[Thomas Huth]

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

[PATCH 3/4] docs/about/removed-features: auto-generate a note for versioned machine types

[Daniel P. Berrangé]

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

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/about/removed-features.rst | 10 ++++++----
 docs/conf.py                    |  2 ++
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst
index 156c0c253c..c120d9ff4f 100644
--- a/docs/about/removed-features.rst
+++ b/docs/about/removed-features.rst
@@ -972,10 +972,12 @@ 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.
+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_DELETION_VERSION|, or older, have been
+removed.
 
 ``s390-virtio`` (removed in 2.6)
 ''''''''''''''''''''''''''''''''
diff --git a/docs/conf.py b/docs/conf.py
index 421ece1024..8b567787ce 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -130,6 +130,7 @@
         minor += 1
 
 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.
@@ -163,6 +164,7 @@
 vars = {
     "CONFDIR": confdir,
     "VER_MACHINE_DEPRECATION_VERSION": ver_machine_deprecation_version,
+    "VER_MACHINE_DELETION_VERSION": ver_machine_deletion_version,
 }
 
 rst_epilog = "".join([
-- 
2.47.1

Re: [PATCH 3/4] docs/about/removed-features: auto-generate a note for versioned machine types

[Thomas Huth]

On 25/02/2025 21.04, Daniel P. Berrangé wrote:
> We remove versioned machine types on a fixed schedule. This allows us
> to auto-generate a paragraph in the removed-features.rst document that
> always has accurate version info.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   docs/about/removed-features.rst | 10 ++++++----
>   docs/conf.py                    |  2 ++
>   2 files changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/about/removed-features.rst b/docs/about/removed-features.rst
> index 156c0c253c..c120d9ff4f 100644
> --- a/docs/about/removed-features.rst
> +++ b/docs/about/removed-features.rst
> @@ -972,10 +972,12 @@ 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.
> +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_DELETION_VERSION|, or older, have been
> +removed.
>   
>   ``s390-virtio`` (removed in 2.6)
>   ''''''''''''''''''''''''''''''''
> diff --git a/docs/conf.py b/docs/conf.py
> index 421ece1024..8b567787ce 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -130,6 +130,7 @@
>           minor += 1
>   
>   ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro)
> +ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro)

As in the previous patch, I think micro=0 would be better here.

  Thomas

[PATCH 4/4] include/hw/boards: add warning about changing deprecation logic

[Daniel P. Berrangé]

If we change the deprecation logic in include/hw/boards.h, we must make
a corresponding change to docs/conf.py and docs/about/deprecated.rst.
Add comments to these files as a warning to future maintainers to keep
these files in sync.

Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
---
 docs/conf.py        | 4 ++++
 include/hw/boards.h | 6 +++++-
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 8b567787ce..d0d3cd10ce 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -129,6 +129,10 @@
     else:
         minor += 1
 
+# These thresholds must match the constants
+# MACHINE_VER_DELETION_MAJOR  & MACHINE_VER_DEPRECATION_MAJOR
+# defined in include/hw/boards.h and the introductory text in
+# docs/about/deprecated.rst
 ver_machine_deprecation_version = "%d.%d.%d" % (major - 3, minor, micro)
 ver_machine_deletion_version = "%d.%d.%d" % (major - 6, minor, micro)
 
diff --git a/include/hw/boards.h b/include/hw/boards.h
index dcfb251cbd..a89a885add 100644
--- a/include/hw/boards.h
+++ b/include/hw/boards.h
@@ -633,7 +633,11 @@ struct MachineState {
 /*
  * How many years/major releases for each phase
  * of the life cycle. Assumes use of versioning
- * scheme where major is bumped each year
+ * scheme where major is bumped each year.
+ *
+ * These values must match the ver_machine_deprecation_version
+ * and ver_machine_deletion_version logic in docs/conf.py and
+ * the text in docs/about/deprecated.rst
  */
 #define MACHINE_VER_DELETION_MAJOR 6
 #define MACHINE_VER_DEPRECATION_MAJOR 3
-- 
2.47.1

Re: [PATCH 4/4] include/hw/boards: add warning about changing deprecation logic

[Thomas Huth]

On 25/02/2025 21.04, Daniel P. Berrangé wrote:
> If we change the deprecation logic in include/hw/boards.h, we must make
> a corresponding change to docs/conf.py and docs/about/deprecated.rst.
> Add comments to these files as a warning to future maintainers to keep
> these files in sync.
> 
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>   docs/conf.py        | 4 ++++
>   include/hw/boards.h | 6 +++++-
>   2 files changed, 9 insertions(+), 1 deletion(-)

Reviewed-by: Thomas Huth <thuth@redhat.com>