From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:57261) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WhUaS-00085o-GA for qemu-devel@nongnu.org; Mon, 05 May 2014 21:54:34 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WhUaL-0006eG-LX for qemu-devel@nongnu.org; Mon, 05 May 2014 21:54:28 -0400 Received: from mx1.redhat.com ([209.132.183.28]:3022) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WhUaL-0006eB-Cd for qemu-devel@nongnu.org; Mon, 05 May 2014 21:54:21 -0400 Received: from int-mx01.intmail.prod.int.phx2.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s461sKtx030481 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Mon, 5 May 2014 21:54:20 -0400 Date: Tue, 6 May 2014 09:54:31 +0800 From: Fam Zheng Message-ID: <20140506015431.GC1574@T430.nay.redhat.com> References: <1399274279-20165-1-git-send-email-famz@redhat.com> <5367A41D.70401@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <5367A41D.70401@redhat.com> Subject: Re: [Qemu-devel] [PATCH] qapi: Document optional arguments' backwards compatibility List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: Kevin Wolf , Luiz Capitulino , qemu-devel@nongnu.org, Markus Armbruster On Mon, 05/05 08:45, Eric Blake wrote: > On 05/05/2014 01:17 AM, Fam Zheng wrote: > > Signed-off-by: Fam Zheng > > --- > > 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