[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] qapi: Document optional arguments' backwards co
From: |
Fam Zheng |
Subject: |
Re: [Qemu-devel] [PATCH] qapi: Document optional arguments' backwards compatibility |
Date: |
Tue, 6 May 2014 09:54:31 +0800 |
User-agent: |
Mutt/1.5.23 (2014-03-12) |
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