On Wed, 7 May 2014 09:57:41 +0800
Fam Zheng <f...@redhat.com> wrote:
> From: Eric Blake <ebl...@redhat.com>
>
> Signed-off-by: Eric Blake <ebl...@redhat.com>
> Signed-off-by: Fam Zheng <f...@redhat.com>
Applied to the qmp branch, thanks.
>
> ---
> v3: More text from Eric.
>
> Signed-off-by: Fam Zheng <f...@redhat.com>
> ---
> 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 d78921f..a6cba0a 100644
> --- a/docs/qapi-code-gen.txt
> +++ b/docs/qapi-code-gen.txt
> @@ -49,10 +49,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
