Eric Blake <ebl...@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 <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,/
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 <ebl...@redhat.com> Thanks!
