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

[Eric Blake]

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 <address@hidden>
> ---
>  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,/

> +
> +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?

Reviewed-by: Eric Blake <address@hidden>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org

signature.asc
Description: OpenPGP digital signature