Re: [Qemu-devel] [PATCH] qapi: Document optional arguments' backwards compatibility

[Eric Blake]

On 05/05/2014 01:17 AM, Fam Zheng wrote:
> Signed-off-by: Fam Zheng <address@hidden>
> ---
>  docs/qapi-code-gen.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
> 
> diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
> index d78921f..d7b19ab 100644
> --- a/docs/qapi-code-gen.txt
> +++ b/docs/qapi-code-gen.txt
> @@ -51,8 +51,10 @@ example of a complex type is:
>  
>  The use of '*' as a prefix to the name means the member is optional.  
> Optional
>  members should always be added to the end of the dictionary to preserve
> -backwards compatibility.

Technically, this is no longer true.  It's a dictionary, so adding new
members in any position does not hurt.  We might as well erase this
sentence since we have numerous counterexamples where it is not being
followed.

> -
> +backwards compatibility. Even there is no strict restriction for default 
> values
> +of those optional arguments between QEMU's versions, the backwards
> +compatibility should be preserved by keeping the user visible behavior
> +unchanged.

Good idea, but reads a little awkwardly.  Maybe:

The default initialization value of an optional argument should not be
changed between versions of QEMU unless the new default maintains
backward compatibility to the user-visible behavior of the old default.

It might also be worth mentioning other rules on default arguments:

On input structures (only mentioned in the 'data' side of a command),
changing from mandatory to optional is safe (older clients will supply
the option, and newer clients can benefit from the default); changing
from optional to mandatory is backwards incompatible (older clients may
be omitting the option, and must continue to work).

On output structures (only mentioned in the 'returns' side of a
command), changing from mandatory to optional is in general unsafe
(older clients may be expecting the field, and could crash if it is
missing), although it can be done if the only way that the optional
argument will be omitted is when it is triggered by the presence of a
new input flag to the command that older clients don't know to send.
Changing from optional to mandatory is safe.

A structure that is used in both input and output of various commands
must consider the backwards compatibility constraints of both directions
of use.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature