[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: |
Eric Blake |
Subject: |
Re: [Qemu-devel] [PATCH v2 13/16] docs/devel/qapi-code-gen: Rewrite compatibility considerations |
Date: |
Tue, 10 Sep 2019 11:42:33 -0500 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101 Thunderbird/60.8.0 |
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
- Re: [Qemu-devel] [PATCH v2 09/16] qapi: Permit alternates with just one branch, (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