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

[Markus Armbruster <armbru@redhat.com>]

Eric Blake <eblake@redhat.com> writes:

> On 9/10/19 1:37 AM, 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>
>> ---
>>  docs/devel/qapi-code-gen.txt | 95 +++++++++++++++++++++++-------------
>>  1 file changed, 60 insertions(+), 35 deletions(-)
>> 
>
>> +== Compatibility considerations ==
>> +
>> +Maintaining backward compatibility at the Client JSON Protocol level
>> +while evolving the schema requires some care.  This section is about
>> +syntactic compatibility.  Necessary, but not sufficient for actual
>> +compatibility.
>
> This last sentence no verb.  Maybe:
>
> s/compatibility.  Necessary/compatibility, which is necessary/
> s/sufficient/sufficient,/

Sold.

>> +
>> +Clients send commands with argument data, and receive command
>> +responses with return data and events with event data.
>> +
>> +Adding opt-in functionality to the send direction is backwards
>> +compatible: adding commands, optional arguments, enumeration values,
>> +union and alternate branches; turning an argument type into an
>> +alternate of that type; making mandatory arguments optional.  Clients
>> +oblivious of the new functionality continue to work.
>> +
>> +Incompatible changes include removing commands, command arguments,
>> +enumeration values, union and alternate branches, adding mandatory
>> +command arguments, and making optional arguments mandatory.
>> +
>> +The specified behavior of an absent optional argument should remain
>> +the same.  With proper documentation, this policy still allows some
>> +flexibility; for example, when an optional 'buffer-size' argument is
>> +specified to default to a sensible buffer size, the actual default
>> +value can still be changed.  The specified default behavior is not the
>> +exact size of the buffer, only that the default size is sensible.
>> +
>> +Adding functionality to the receive direction is generally backwards
>> +compatible: adding events, adding return and event data members.
>> +Clients are expected to ignore the ones they don't know.
>> +
>> +Removing "unreachable" stuff like events that can't be triggered
>> +anymore, optional return or event data members that can't be sent
>> +anymore, and return or event data member (enumeration) values that
>> +can't be sent anymore makes no difference to clients, except for
>> +introspection.  The latter can conceivably confuse clients, so tread
>> +carefully.
>> +
>> +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.
>
> Worth mentioning that type names themselves are NOT part of the
> interface, and may be freely renamed?

Care to suggest a suitable sentence?

> Reviewed-by: Eric Blake <eblake@redhat.com>

Thanks!