[Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility

[Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility

[Fam Zheng]

Signed-off-by: Fam Zheng <famz@redhat.com>

---
v2: Employ the text suggested by Eric. (Thanks!)

Signed-off-by: Fam Zheng <famz@redhat.com>
---
 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

Re: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2290 bytes --]

On 05/05/2014 08:05 PM, Fam Zheng wrote:
> Signed-off-by: Fam Zheng <famz@redhat.com>
> 
> ---
> 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 <eblake@redhat.com>

> 
> Signed-off-by: Fam Zheng <famz@redhat.com>
> ---
>  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.

> +
> +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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH v2] qapi: Document optional arguments' backwards compatibility

[Fam Zheng]

On Tue, 05/06 19:30, Eric Blake wrote:
> On 05/05/2014 08:05 PM, Fam Zheng wrote:
> > Signed-off-by: Fam Zheng <famz@redhat.com>
> > 
> > ---
> > 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 <eblake@redhat.com>

Gladly!

> 
> > 
> > Signed-off-by: Fam Zheng <famz@redhat.com>
> > ---
> >  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
>