[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards
From: |
Fam Zheng |
Subject: |
Re: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility |
Date: |
Wed, 7 May 2014 09:57:52 +0800 |
User-agent: |
Mutt/1.5.23 (2014-03-12) |
On Tue, 05/06 19:30, Eric Blake wrote:
> On 05/05/2014 08:05 PM, Fam Zheng wrote:
> > Signed-off-by: Fam Zheng <address@hidden>
> >
> > ---
> > v2: Employ the text suggested by Eric. (Thanks!)
>
> Since much of it is my wording, it's probably better to credit me as an
> author, by adding:
>
> Signed-off-by: Eric Blake <address@hidden>
Gladly!
>
> >
> > Signed-off-by: Fam Zheng <address@hidden>
> > ---
> > docs/qapi-code-gen.txt | 26 ++++++++++++++++++++++----
> > 1 file changed, 22 insertions(+), 4 deletions(-)
> >
> > +The use of '*' as a prefix to the name means the member is optional.
> > +
> > +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.
>
> Maybe worth adding:
>
> With proper documentation, this policy still allows some flexibility;
> for example, documenting that a default of 0 picks an optimal buffer
> size allows one release to declare the optimal size at 512 while another
> release declares the optimal size at 4096 - the user-visible behavior is
> not the bytes used by the buffer, but the fact that the buffer was
> optimal size.
OK, will add this and your s-o-b in V3.
Thanks,
Fam
>
> > +
> > +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
>