[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite comp
From: |
Eric Blake |
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 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 |
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 <address@hidden>
> Reviewed-by: Eric Blake <address@hidden>
> ---
> 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
signature.asc
Description: OpenPGP digital signature
- [Qemu-devel] [PATCH v3 00/16] qapi: Schema language cleanups & doc improvements, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 02/16] qapi: Drop check_type()'s redundant parameter @allow_optional, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 05/16] tests/qapi-schema: Demonstrate bad reporting of funny characters, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 03/16] qapi: Drop support for boxed alternate arguments, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 04/16] docs/devel/qapi-code-gen: Minor specification fixes, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 01/16] scripts/git.orderfile: Match QAPI schema more precisely, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 06/16] qapi: Restrict strings to printable ASCII, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 07/16] qapi: Drop support for escape sequences other than \\, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations, Markus Armbruster, 2019/09/13
- Re: [Qemu-devel] [PATCH v3 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations,
Eric Blake <=
- [Qemu-devel] [PATCH v3 16/16] qapi: Tweak code to match docs/devel/qapi-code-gen.txt, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 10/16] qapi: Permit omitting all flat union branches, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 08/16] qapi: Permit 'boxed' with empty type, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 12/16] docs/devel/qapi-code-gen: Reorder sections for readability, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 15/16] docs/devel/qapi-code-gen: Improve QAPI schema language doc, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 09/16] qapi: Permit alternates with just one branch, Markus Armbruster, 2019/09/13
- [Qemu-devel] [PATCH v3 11/16] qapi: Adjust frontend errors to say enum value, not member, Markus Armbruster, 2019/09/13