From: Eric Blake <eblake@redhat.com>
To: Markus Armbruster <armbru@redhat.com>, qemu-devel@nongnu.org
Cc: marcandre.lureau@redhat.com, mdroth@linux.vnet.ibm.com
Subject: Re: [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations
Date: Tue, 17 Sep 2019 11:22:16 -0500 [thread overview]
Message-ID: <afbfd0e5-4441-e028-ec3e-ca7129fca342@redhat.com> (raw)
In-Reply-To: <20190913201349.24332-14-armbru@redhat.com>
[-- Attachment #1.1: Type: text/plain, Size: 1876 bytes --]
On 9/13/19 3:13 PM, Markus Armbruster wrote:
> We have some compatibility advice buried in sections "Enumeration
> types" and "Struct types". Compatibility is actually about commands
> and events. It devolves to the types used there. All kinds of types,
> not just enumerations and structs.
>
> Replace the existing advice by a new section "Compatibility
> considerations".
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> Reviewed-by: Eric Blake <eblake@redhat.com>
> ---
> docs/devel/qapi-code-gen.txt | 95 +++++++++++++++++++++++-------------
> 1 file changed, 60 insertions(+), 35 deletions(-)
You asked me a question on v2 about a possible sentence to add about
renaming types. Up to you if you want to fold that one in here, or leave
it for a separate patch.
> +Incompatible changes include removing return and event data members.
> +
> +Any change to a command definition's 'data' or one of the types used
> +there (recursively) needs to consider send direction compatibility.
> +
> +Any change to a command definition's 'return', an event definition's
> +'data', or one of the types used there (recursively) needs to consider
> +receive direction compatibility.
> +
> +Any change to types used in both contexts need to consider both.
> +
> +Members of enumeration types, complex types and alternate types may be
> +reordered freely. For enumerations and alternate types, this doesn't
> +affect the wire encoding. For complex types, this might make the
> +implementation emit JSON object members in a different order, which
> +the Client JSON Protocol permits.
> +
> +
> == Code generation ==
>
> The QAPI code generator qapi-gen.py generates code and documentation
>
--
Eric Blake, Principal Software Engineer
Red Hat, Inc. +1-919-301-3226
Virtualization: qemu.org | libvirt.org
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
next prev parent reply other threads:[~2019-09-17 16:24 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-09-13 20:13 [Qemu-devel] [PATCH v3 00/16] qapi: Schema language cleanups & doc improvements Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 01/16] scripts/git.orderfile: Match QAPI schema more precisely Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 02/16] qapi: Drop check_type()'s redundant parameter @allow_optional Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 03/16] qapi: Drop support for boxed alternate arguments Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 04/16] docs/devel/qapi-code-gen: Minor specification fixes Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 05/16] tests/qapi-schema: Demonstrate bad reporting of funny characters Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 06/16] qapi: Restrict strings to printable ASCII Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 07/16] qapi: Drop support for escape sequences other than \\ Markus Armbruster
2019-09-17 16:18 ` Eric Blake
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 08/16] qapi: Permit 'boxed' with empty type Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 09/16] qapi: Permit alternates with just one branch Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 10/16] qapi: Permit omitting all flat union branches Markus Armbruster
2019-09-17 16:20 ` Eric Blake
2019-09-23 11:46 ` Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 11/16] qapi: Adjust frontend errors to say enum value, not member Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 12/16] docs/devel/qapi-code-gen: Reorder sections for readability Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations Markus Armbruster
2019-09-17 16:22 ` Eric Blake [this message]
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 15/16] docs/devel/qapi-code-gen: Improve QAPI schema language doc Markus Armbruster
2019-09-13 20:13 ` [Qemu-devel] [PATCH v3 16/16] qapi: Tweak code to match docs/devel/qapi-code-gen.txt Markus Armbruster
2019-09-14 2:49 ` [Qemu-devel] [PATCH v3 00/16] qapi: Schema language cleanups & doc improvements no-reply
2019-09-17 16:31 ` Eric Blake
2019-09-23 11:49 ` Markus Armbruster
2019-09-23 18:29 ` Markus Armbruster
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=afbfd0e5-4441-e028-ec3e-ca7129fca342@redhat.com \
--to=eblake@redhat.com \
--cc=armbru@redhat.com \
--cc=marcandre.lureau@redhat.com \
--cc=mdroth@linux.vnet.ibm.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).