From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:51983) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WhK9U-0004Yn-W1 for qemu-devel@nongnu.org; Mon, 05 May 2014 10:46:01 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WhK9P-0007Yv-Gs for qemu-devel@nongnu.org; Mon, 05 May 2014 10:45:56 -0400 Received: from mx1.redhat.com ([209.132.183.28]:12996) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WhK9P-0007Yf-8U for qemu-devel@nongnu.org; Mon, 05 May 2014 10:45:51 -0400 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (8.14.4/8.14.4) with ESMTP id s45EjoOw008241 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Mon, 5 May 2014 10:45:50 -0400 Message-ID: <5367A41D.70401@redhat.com> Date: Mon, 05 May 2014 08:45:49 -0600 From: Eric Blake MIME-Version: 1.0 References: <1399274279-20165-1-git-send-email-famz@redhat.com> In-Reply-To: <1399274279-20165-1-git-send-email-famz@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="KXHMFJVBUrbWiVe6vlVI7kdFJd0dJLE2W" Subject: Re: [Qemu-devel] [PATCH] qapi: Document optional arguments' backwards compatibility List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Fam Zheng , qemu-devel@nongnu.org Cc: Kevin Wolf , Markus Armbruster , Luiz Capitulino This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --KXHMFJVBUrbWiVe6vlVI7kdFJd0dJLE2W Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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(-) >=20 > 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: > =20 > 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 preserv= e > -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. > - > +backwards compatibility. Even there is no strict restriction for defau= lt 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. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --KXHMFJVBUrbWiVe6vlVI7kdFJd0dJLE2W Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJTZ6QdAAoJEKeha0olJ0NqbaMIAKYzHiyy1wKmL01Kj+oaC6aH SBMGmmhUVmq3aE0rNxlmb6riEiqztNXDbv4rEjCNOJQyijjU+c4zmdR7LhxJoLMv dysK1DZutbHsZS5MGOVp1lnUPsdKXXBw8QzY8PcQhtWgv/B391px8Xs/7sGQWDbi M+fjvy7l5QFsKyC0hVFWVHNUJJ4DL4JKYOOf9xkILscgXHSoteUTKG/R4DKfLwYF civJqKszhwd3av9YLJpcFluZ5rt+wVzGhRHezyFsbuTZJTzGr7X6rxYC3F0qoOdr lS+Pjtxlu+bMHyZQy+X6yT6PMdstLJWDpTrctDh2iYab4E1XLBFEhg78hel/npQ= =stOA -----END PGP SIGNATURE----- --KXHMFJVBUrbWiVe6vlVI7kdFJd0dJLE2W--