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

[Fam Zheng]

On Mon, 05/05 08:45, Eric Blake wrote:
> 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.

Good idea.

> 
> > -
> > +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.
> 

Thanks for the suggestion, I'll use your text and send another revision.

Fam