From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:32777) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WhUlT-0005AB-NM for qemu-devel@nongnu.org; Mon, 05 May 2014 22:05:57 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WhUlN-0003o8-De for qemu-devel@nongnu.org; Mon, 05 May 2014 22:05:51 -0400 From: Fam Zheng Date: Tue, 6 May 2014 10:05:53 +0800 Message-Id: <1399341953-14387-1-git-send-email-famz@redhat.com> Subject: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Kevin Wolf , qemu-trivial@nongnu.org, Markus Armbruster , Luiz Capitulino Signed-off-by: Fam Zheng --- v2: Employ the text suggested by Eric. (Thanks!) Signed-off-by: Fam Zheng --- docs/qapi-code-gen.txt | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt index d78921f..3e5cfd5 100644 --- a/docs/qapi-code-gen.txt +++ b/docs/qapi-code-gen.txt @@ -49,10 +49,28 @@ example of a complex type is: { 'type': 'MyType', 'data': { 'member1': 'str', 'member2': 'int', '*member3': 'str' } } -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. - +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. + +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. A complex type definition can specify another complex type as its base. In this case, the fields of the base type are included as top-level fields -- 1.9.2