[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 13/16] docs/devel/qapi-code-gen: Rewrite comp
From: |
Markus Armbruster |
Subject: |
Re: [Qemu-devel] [PATCH v2 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations |
Date: |
Mon, 23 Sep 2019 13:44:49 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/26.2 (gnu/linux) |
Eric Blake <address@hidden> writes:
> On 9/13/19 10:05 AM, Markus Armbruster wrote:
>
>>>> +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.
>>>
>>> Worth mentioning that type names themselves are NOT part of the
>>> interface, and may be freely renamed?
>>
>> Care to suggest a suitable sentence?
>
> Although member names within a type cannot be changed without affecting
> compatibility,
This part seems redundant with the previous paragraph.
> changes to type names themselves do not affect the
> protocol. As such, complex types may be freely renamed or refactored,
All types (enums, structs, simple & flat unions, alternates) actually,
not just complex ones (structs, unions).
> such as splitting members from one type into a common base type, as long
> as the resulting set of members remain compatible.
What does it mean for a set of members to be compatible? We don't
actually define that...
What about:
Since type names are not visible in the Client JSON Protocol, types
may be freely renamed. Even certain refactorings are invisible, such
as splitting members from one type into a common base type.
- Re: [Qemu-devel] [PATCH v2 12/16] docs/devel/qapi-code-gen: Reorder sections for readability, (continued)
[Qemu-devel] [PATCH v2 14/16] docs/devel/qapi-code-gen: Rewrite introduction to schema, Markus Armbruster, 2019/09/10
[Qemu-devel] [PATCH v2 08/16] qapi: Permit 'boxed' with empty type, Markus Armbruster, 2019/09/10
[Qemu-devel] [PATCH v2 15/16] docs/devel/qapi-code-gen: Improve QAPI schema language doc, Markus Armbruster, 2019/09/10