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

[PATCH] 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.  Adjust the doc and the
exceptions to the ruling practice.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst |  4 ++--
 docs/interop/firmware.json   |  4 ++--
 qapi/accelerator.json        |  6 +++---
 qapi/crypto.json             |  2 +-
 qga/qapi-schema.json         | 38 ++++++++++++++++++------------------
 5 files changed, 27 insertions(+), 27 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
 ##
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 7b937713e6..531fb8f8e0 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -110,7 +110,7 @@
 #
 # Returns: The unique integer id passed in by the client
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-sync',
   'data':    { 'id': 'int' },
@@ -120,7 +120,7 @@
 # @guest-ping:
 #     Ping the guest agent, a non-error return implies success
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-ping' }
 
@@ -172,7 +172,7 @@
 # @success-response: whether command returns a response on success
 #     (since 1.7)
 #
-# Since: 1.1.0
+# Since: 1.1
 ##
 { 'struct': 'GuestAgentCommandInfo',
   'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } }
@@ -185,7 +185,7 @@
 #
 # @supported_commands: Information about guest agent commands
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'struct': 'GuestAgentInfo',
   'data': { 'version': 'str',
@@ -195,7 +195,7 @@
 # @guest-info:
 #     Get some information about the guest agent.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-info',
   'returns': 'GuestAgentInfo' }
@@ -213,7 +213,7 @@
 # when running with --no-shutdown, by issuing the `query-status` QMP
 # command to confirm the VM status is "shutdown".
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
   'success-response': false }
@@ -228,7 +228,7 @@
 #
 # Returns: Guest file handle
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-open',
   'data':    { 'path': 'str', '*mode': 'str' },
@@ -240,7 +240,7 @@
 #
 # @handle: filehandle returned by `guest-file-open`
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-close',
   'data': { 'handle': 'int' } }
@@ -256,7 +256,7 @@
 #
 # @eof: whether EOF was encountered during read operation.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'struct': 'GuestFileRead',
   'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
@@ -273,7 +273,7 @@
 # @count: maximum number of bytes to read (default is 4KB, maximum is
 #     48MB)
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-read',
   'data':    { 'handle': 'int', '*count': 'int' },
@@ -288,7 +288,7 @@
 #
 # @eof: whether EOF was encountered during write operation.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'struct': 'GuestFileWrite',
   'data': { 'count': 'int', 'eof': 'bool' } }
@@ -304,7 +304,7 @@
 # @count: bytes to write (actual bytes, after base64-decode), default
 #     is all content in buf-b64 buffer after base64 decoding
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-write',
   'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
@@ -318,7 +318,7 @@
 #
 # @eof: whether EOF was encountered during file seek
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'struct': 'GuestFileSeek',
   'data': { 'position': 'int', 'eof': 'bool' } }
@@ -364,7 +364,7 @@
 #
 # @whence: Symbolic or numeric code for interpreting offset
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-seek',
   'data':    { 'handle': 'int', 'offset': 'int',
@@ -377,7 +377,7 @@
 #
 # @handle: filehandle returned by `guest-file-open`
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-file-flush',
   'data': { 'handle': 'int' } }
@@ -390,7 +390,7 @@
 #
 # @frozen: all non-network guest filesystems frozen
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'enum': 'GuestFsfreezeStatus',
   'data': [ 'thawed', 'frozen' ],
@@ -404,7 +404,7 @@
 #    result of some other guest processes having issued an fs
 #    freeze/thaw.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-fsfreeze-status',
   'returns': 'GuestFsfreezeStatus',
@@ -427,7 +427,7 @@
 #    Volume Shadow-copy Service DLL helper.  The frozen state is
 #    limited for up to 10 seconds by VSS.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-fsfreeze-freeze',
   'returns': 'int',
@@ -464,7 +464,7 @@
 #    filesystems were unfrozen before this call, and that the
 #    filesystem state may have changed before issuing this command.
 #
-# Since: 0.15.0
+# Since: 0.15
 ##
 { 'command': 'guest-fsfreeze-thaw',
   'returns': 'int',
-- 
2.55.0

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

[Daniel P. Berrangé]

On Mon, Nov 02, 2026 at 03:56:27PM +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.  Adjust the doc and the
> exceptions to the ruling practice.

Shortening to 2 digits is sensible given our current version
numbering scheme. The 3rd digit is exclusively for stable
branches that should not be forking qapi schemas.

This only applies since our switch to this versioning scheme,
which was in 3.0.0, so anything earlier than this should not
be changed IMHO.

> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst |  4 ++--
>  docs/interop/firmware.json   |  4 ++--
>  qapi/accelerator.json        |  6 +++---
>  qapi/crypto.json             |  2 +-
>  qga/qapi-schema.json         | 38 ++++++++++++++++++------------------
>  5 files changed, 27 insertions(+), 27 deletions(-)
> 

> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> index 7b937713e6..531fb8f8e0 100644
> --- a/qga/qapi-schema.json
> +++ b/qga/qapi-schema.json
> @@ -110,7 +110,7 @@
>  #
>  # Returns: The unique integer id passed in by the client
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-sync',
>    'data':    { 'id': 'int' },
> @@ -120,7 +120,7 @@
>  # @guest-ping:
>  #     Ping the guest agent, a non-error return implies success
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-ping' }
>  
> @@ -172,7 +172,7 @@
>  # @success-response: whether command returns a response on success
>  #     (since 1.7)
>  #
> -# Since: 1.1.0
> +# Since: 1.1
>  ##
>  { 'struct': 'GuestAgentCommandInfo',
>    'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } }
> @@ -185,7 +185,7 @@
>  #
>  # @supported_commands: Information about guest agent commands
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'struct': 'GuestAgentInfo',
>    'data': { 'version': 'str',
> @@ -195,7 +195,7 @@
>  # @guest-info:
>  #     Get some information about the guest agent.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-info',
>    'returns': 'GuestAgentInfo' }
> @@ -213,7 +213,7 @@
>  # when running with --no-shutdown, by issuing the `query-status` QMP
>  # command to confirm the VM status is "shutdown".
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-shutdown', 'data': { '*mode': 'str' },
>    'success-response': false }
> @@ -228,7 +228,7 @@
>  #
>  # Returns: Guest file handle
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-open',
>    'data':    { 'path': 'str', '*mode': 'str' },
> @@ -240,7 +240,7 @@
>  #
>  # @handle: filehandle returned by `guest-file-open`
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-close',
>    'data': { 'handle': 'int' } }
> @@ -256,7 +256,7 @@
>  #
>  # @eof: whether EOF was encountered during read operation.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'struct': 'GuestFileRead',
>    'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } }
> @@ -273,7 +273,7 @@
>  # @count: maximum number of bytes to read (default is 4KB, maximum is
>  #     48MB)
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-read',
>    'data':    { 'handle': 'int', '*count': 'int' },
> @@ -288,7 +288,7 @@
>  #
>  # @eof: whether EOF was encountered during write operation.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'struct': 'GuestFileWrite',
>    'data': { 'count': 'int', 'eof': 'bool' } }
> @@ -304,7 +304,7 @@
>  # @count: bytes to write (actual bytes, after base64-decode), default
>  #     is all content in buf-b64 buffer after base64 decoding
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-write',
>    'data':    { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' },
> @@ -318,7 +318,7 @@
>  #
>  # @eof: whether EOF was encountered during file seek
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'struct': 'GuestFileSeek',
>    'data': { 'position': 'int', 'eof': 'bool' } }
> @@ -364,7 +364,7 @@
>  #
>  # @whence: Symbolic or numeric code for interpreting offset
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-seek',
>    'data':    { 'handle': 'int', 'offset': 'int',
> @@ -377,7 +377,7 @@
>  #
>  # @handle: filehandle returned by `guest-file-open`
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-file-flush',
>    'data': { 'handle': 'int' } }
> @@ -390,7 +390,7 @@
>  #
>  # @frozen: all non-network guest filesystems frozen
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'enum': 'GuestFsfreezeStatus',
>    'data': [ 'thawed', 'frozen' ],
> @@ -404,7 +404,7 @@
>  #    result of some other guest processes having issued an fs
>  #    freeze/thaw.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-fsfreeze-status',
>    'returns': 'GuestFsfreezeStatus',
> @@ -427,7 +427,7 @@
>  #    Volume Shadow-copy Service DLL helper.  The frozen state is
>  #    limited for up to 10 seconds by VSS.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-fsfreeze-freeze',
>    'returns': 'int',
> @@ -464,7 +464,7 @@
>  #    filesystems were unfrozen before this call, and that the
>  #    filesystem state may have changed before issuing this command.
>  #
> -# Since: 0.15.0
> +# Since: 0.15
>  ##
>  { 'command': 'guest-fsfreeze-thaw',
>    'returns': 'int',

Don't change any of these, since at that vintage, the 3rd digit
was significant.

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 :|

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

[Markus Armbruster]

Daniel P. Berrangé <berrange@redhat.com> writes:

> On Mon, Nov 02, 2026 at 03:56:27PM +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.  Adjust the doc and the
>> exceptions to the ruling practice.
>
> Shortening to 2 digits is sensible given our current version
> numbering scheme. The 3rd digit is exclusively for stable
> branches that should not be forking qapi schemas.
>
> This only applies since our switch to this versioning scheme,
> which was in 3.0.0, so anything earlier than this should not
> be changed IMHO.

Makes sense.

>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>>  docs/devel/qapi-code-gen.rst |  4 ++--
>>  docs/interop/firmware.json   |  4 ++--
>>  qapi/accelerator.json        |  6 +++---
>>  qapi/crypto.json             |  2 +-
>>  qga/qapi-schema.json         | 38 ++++++++++++++++++------------------
>>  5 files changed, 27 insertions(+), 27 deletions(-)
>> 
>
>> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
>> index 7b937713e6..531fb8f8e0 100644
>> --- a/qga/qapi-schema.json
>> +++ b/qga/qapi-schema.json
>> @@ -110,7 +110,7 @@
>>  #
>>  # Returns: The unique integer id passed in by the client
>>  #
>> -# Since: 0.15.0
>> +# Since: 0.15
>>  ##
>>  { 'command': 'guest-sync',
>>    'data':    { 'id': 'int' },

[...]

>> @@ -464,7 +464,7 @@
>>  #    filesystems were unfrozen before this call, and that the
>>  #    filesystem state may have changed before issuing this command.
>>  #
>> -# Since: 0.15.0
>> +# Since: 0.15
>>  ##
>>  { 'command': 'guest-fsfreeze-thaw',
>>    'returns': 'int',
>
> Don't change any of these, since at that vintage, the 3rd digit
> was significant.

Done in v2.

Thank you!