On 9/13/19 3:13 PM, 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>
> Reviewed-by: Eric Blake <eblake@redhat.com>
> ---
>  docs/devel/qapi-code-gen.txt | 95 +++++++++++++++++++++++-------------
>  1 file changed, 60 insertions(+), 35 deletions(-)

You asked me a question on v2 about a possible sentence to add about
renaming types. Up to you if you want to fold that one in here, or leave
it for a separate patch.


> +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.
> +
> +
>  == Code generation ==
>  
>  The QAPI code generator qapi-gen.py generates code and documentation
> 

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