From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:60168) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Whr7F-0001Wy-VZ for qemu-devel@nongnu.org; Tue, 06 May 2014 21:57:55 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Whr78-00023d-6v for qemu-devel@nongnu.org; Tue, 06 May 2014 21:57:49 -0400 Date: Wed, 7 May 2014 09:57:52 +0800 From: Fam Zheng Message-ID: <20140507015752.GH1574@T430.nay.redhat.com> References: <1399341953-14387-1-git-send-email-famz@redhat.com> <53698CBA.7040901@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <53698CBA.7040901@redhat.com> Subject: Re: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: Kevin Wolf , qemu-trivial@nongnu.org, Luiz Capitulino , qemu-devel@nongnu.org, Markus Armbruster On Tue, 05/06 19:30, Eric Blake wrote: > On 05/05/2014 08:05 PM, Fam Zheng wrote: > > Signed-off-by: Fam Zheng > > > > --- > > 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 Gladly! > > > > > Signed-off-by: Fam Zheng > > --- > > 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 >