On 05/05/2014 08:05 PM, Fam Zheng wrote: > Signed-off-by: Fam Zheng <f...@redhat.com> > > --- > 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 <ebl...@redhat.com> > > Signed-off-by: Fam Zheng <f...@redhat.com> > --- > 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. > + > +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
