[PATCH v2] qapi: Consistently use x.y with since

[PATCH v2] qapi: Consistently use x.y with since

[Markus Armbruster]

docs/devel/qapi-code-gen.rst documents "Since: x.y.z" and "(since
x.y.z)", but we almost always use just x.y.  Makes sense, because .z
is exclusively for stable branches, where we generally don't mess with
QAPI schemas.

Adjust the doc and the exceptions to the ruling practice.  Do not
touch versions prior to 3.0.0, because .z was not for stable branches
back then.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
v2: Don't change versions prior to 3.0.0, and improve commit message
    [Daniel]

 docs/devel/qapi-code-gen.rst | 4 ++--
 docs/interop/firmware.json   | 4 ++--
 qapi/accelerator.json        | 6 +++---
 qapi/crypto.json             | 2 +-
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index b1cc5b5f0d..f276a2bc9b 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1001,7 +1001,7 @@ indented like this::
 .. FIXME union branches should be described, too.
 
 Extensions added after the definition was first released carry a
-"(since x.y.z)" comment.
+"(since x.y)" comment.
 
 The feature descriptions must be preceded by a blank line and then a
 line "Features:", like this::
@@ -1034,7 +1034,7 @@ detailing a relevant error condition.  For example::
  #     - If @device does not exist, DeviceNotFound
  #     - Any other error returns a GenericError.
 
-A "Since: x.y.z" tagged section lists the release that introduced the
+A "Since: x.y" tagged section lists the release that introduced the
 definition.
 
 "TODO" sections are not rendered (they are for developers, not users of
diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 1efd32c631..c8bf0ef1a1 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -283,7 +283,7 @@
 #     and can be shared between multiple guests.  No NVRAM template
 #     will be specified.
 #
-# Since: 7.0.0
+# Since: 7.0
 ##
 { 'enum': 'FirmwareFlashMode',
   'data': [ 'split', 'combined', 'stateless' ] }
@@ -296,7 +296,7 @@
 #
 # @mode: Describes how the firmware build handles code versus variable
 #     storage.  If not present, it must be treated as if it was
-#     configured with value @split.  Since: 7.0.0
+#     configured with value @split.  (Since: 7.0)
 #
 # @executable: Identifies the firmware executable.  The @mode
 #     indicates whether there will be an associated NVRAM template
diff --git a/qapi/accelerator.json b/qapi/accelerator.json
index efc0fa8141..e422fc7ee6 100644
--- a/qapi/accelerator.json
+++ b/qapi/accelerator.json
@@ -78,7 +78,7 @@
 #
 # @xen: Xen
 #
-# Since: 10.2.0
+# Since: 10.2
 ##
 { 'enum': 'Accelerator', 'data': ['hvf', 'kvm', 'mshv', 'nvmm', 'qtest', 'tcg', 'whpx', 'xen'] }
 
@@ -91,7 +91,7 @@
 # @present: the list of accelerators that are built into this
 #     executable
 #
-# Since: 10.2.0
+# Since: 10.2
 ##
 { 'struct': 'AcceleratorInfo', 'data': {'enabled': 'Accelerator', 'present': ['Accelerator']} }
 
@@ -101,7 +101,7 @@
 #
 # Returns: @AcceleratorInfo
 #
-# Since: 10.2.0
+# Since: 10.2
 #
 # .. qmp-example::
 #
diff --git a/qapi/crypto.json b/qapi/crypto.json
index a8d753d360..0fd1af1b68 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -57,7 +57,7 @@
 #
 # @ripemd160: RIPEMD-160.  (since 2.7)
 #
-# @sm3: SM3.  (since 9.2.0)
+# @sm3: SM3.  (since 9.2)
 #
 # Since: 2.6
 ##
-- 
2.55.0

Re: [PATCH v2] qapi: Consistently use x.y with since

[Daniel P. Berrangé]

On Tue, Nov 03, 2026 at 08:33:11AM +0100, Markus Armbruster wrote:
> docs/devel/qapi-code-gen.rst documents "Since: x.y.z" and "(since
> x.y.z)", but we almost always use just x.y.  Makes sense, because .z
> is exclusively for stable branches, where we generally don't mess with
> QAPI schemas.
> 
> Adjust the doc and the exceptions to the ruling practice.  Do not
> touch versions prior to 3.0.0, because .z was not for stable branches
> back then.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> v2: Don't change versions prior to 3.0.0, and improve commit message
>     [Daniel]
> 
>  docs/devel/qapi-code-gen.rst | 4 ++--
>  docs/interop/firmware.json   | 4 ++--
>  qapi/accelerator.json        | 6 +++---
>  qapi/crypto.json             | 2 +-
>  4 files changed, 8 insertions(+), 8 deletions(-)

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>


With regards,
Daniel
-- 
|: https://berrange.com       ~~        https://hachyderm.io/@berrange :|
|: https://libvirt.org          ~~          https://entangle-photo.org :|
|: https://pixelfed.art/berrange   ~~    https://fstop138.berrange.com :|