Re: [Qemu-devel] [PATCH v2 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations

[Markus Armbruster]

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.