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 <arm...@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,/ > + > +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 <ebl...@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. +1-919-301-3226 Virtualization: qemu.org | libvirt.org
signature.asc
Description: OpenPGP digital signature