Re: [PATCH 11/48] qapi: deprecate 'alias' field in MachineInfo

[Markus Armbruster <armbru@redhat.com>]

Daniel P. Berrangé <berrange@redhat.com> writes:

> It is replaced by the new 'aliases' field.
>
> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
> ---
>  docs/about/deprecated.rst | 7 +++++++
>  qapi/machine.json         | 4 +++-
>  2 files changed, 10 insertions(+), 1 deletion(-)
>
> diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst
> index 0891bbc44de..88b21a018f9 100644
> --- a/docs/about/deprecated.rst
> +++ b/docs/about/deprecated.rst
> @@ -182,6 +182,13 @@ execution.  This special treatment of ``"no"`` is deprecated.  Use an
>  empty string instead.  In a future version, ``"no"`` will be treated as
>  a plain file name.
>  
> +``alias`` field of ``MachineInfo`` (since 12.0)
> +'''''''''''''''''''''''''''''''''''''''''''''''

I prefer to talk about commands and events instead of types here.
Commands and events are what the user cares about.  Types are detail.

Existing notes nearby use "member", not "field".

Together:

   ``query-machines`` return value member ``alias`` (since 12.0)

> +
> +The ``MachineInfo`` struct now has an ``aliases`` field which
> +can report multiple aliases per machine, thus the ``alias``
> +field is now redundant.
> +

We commonly phrase these notes like "don't use this, use that".  Your
note conveys this, but it's not explicit.  Maybe

   Use member ``aliases`` instead.

would suffice.

We should've used a list of aliases from day one.

>  Human Machine Protocol (HMP) commands
>  -------------------------------------
>  
> diff --git a/qapi/machine.json b/qapi/machine.json
> index c25a492a4e8..40fda705462 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -199,11 +199,13 @@
>  # Features:
>  #
>  # @unstable: Member @compat-props is experimental.

Blank line, please.

> +# @deprecated: Member @alias is replaced by @aliases.

We commonly phrase this as

   # @deprecated: Member @alias is deprecated.  Use @aliases instead.

>  #
>  # Since: 1.2
>  ##
>  { 'struct': 'MachineInfo',
> -  'data': { 'name': 'str', '*alias': 'str',
> +  'data': { 'name': 'str',
> +            '*alias': { 'type': 'str', 'features': ['deprecated'] },
>              '*aliases': ['str'],
>              '*is-default': 'bool', 'cpu-max': 'int',
>              'hotpluggable-cpus': 'bool',  'numa-mem-supported': 'bool',