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

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

[Fam Zheng]

Signed-off-by: Fam Zheng <famz@redhat.com>
---
 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.
-
+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.
 
 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] qapi: Document optional arguments' backwards compatibility

[Eric Blake]

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

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

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

-- 
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] qapi: Document optional arguments' backwards compatibility

[Fam Zheng]

On Mon, 05/05 08:45, Eric Blake wrote:
> On 05/05/2014 01:17 AM, Fam Zheng wrote:
> > Signed-off-by: Fam Zheng <famz@redhat.com>
> > ---
> >  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