[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 37/38] qapi: Document optional arguments' backwards c
From: |
Luiz Capitulino |
Subject: |
[Qemu-devel] [PULL 37/38] qapi: Document optional arguments' backwards compatibility |
Date: |
Thu, 8 May 2014 14:53:01 -0400 |
From: Eric Blake <address@hidden>
Signed-off-by: Eric Blake <address@hidden>
Signed-off-by: Fam Zheng <address@hidden>
Signed-off-by: Luiz Capitulino <address@hidden>
---
docs/qapi-code-gen.txt | 32 ++++++++++++++++++++++++++++----
1 file changed, 28 insertions(+), 4 deletions(-)
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 051d109..26312d8 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -60,10 +60,34 @@ 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.
+
+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.
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.0
- [Qemu-devel] [PULL 28/38] qapi: Drop redundant, unclean error_is_set(), (continued)
- [Qemu-devel] [PULL 28/38] qapi: Drop redundant, unclean error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 30/38] qapi: Clean up fragile use of error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 29/38] tests/qapi-schema: Drop superfluous error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 31/38] qga: Clean up fragile use of error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 34/38] dump: Drop pointless error_is_set(), DumpState member errp, Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 38/38] Revert "qapi: Clean up superfluous null check in qapi_dealloc_type_str()", Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 35/38] qmp: Don't use error_is_set() to suppress additional errors, Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 33/38] qemu-option: Clean up fragile use of error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 36/38] qmp: use valid JSON in transaction example, Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 32/38] qga: Drop superfluous error_is_set(), Luiz Capitulino, 2014/05/08
- [Qemu-devel] [PULL 37/38] qapi: Document optional arguments' backwards compatibility,
Luiz Capitulino <=
- Re: [Qemu-devel] [PULL 00/38] QMP queue, Peter Maydell, 2014/05/09