Re: [PATCH] qapi/migration: Make migration parameter @local consistently unstable

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> On Sat, Sep 12, 2026 at 06:53:50AM +0200, Markus Armbruster wrote:
>> @local is unstable in MigrationParameters, but not in
>> MigrationParameter.  Fix the latter.
>> 
>> Fixes: c9affb8e9b (qapi: add local migration parameter)
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Peter Xu <peterx@redhat.com>
>
> To avoid this in the future, can we further simplify MigrationParameter in
> qapi/?  E.g. either dropping the @unstable completely (by mentioning in its
> doc to reference MigrationParameters),

Or mark the entire MigrationParameter unstable.

> doc to reference MigrationParameters), or I also wonder if there is way we
> can completely avoid some struct to be visible in doc, so we can drop it;
> currently MigrationParameter still shows all fields "Not Documented".

The entire QAPI schema goes into the "QEMU QMP Reference Manual".  Even
types that aren't used in QMP, which is undesirable.

We have code to find the types used in QMP.  query-qmp-schema uses it.
We never got around to use it in the doc generator, too.

However, Marc-André's work to improve QOM introspection complicates
matters.  It exposes QAPI types in QOM introspection.  Types so exposed
are then part of the external interface, but that's not captured in the
QAPI schema, only in QOM property definitions.  We're probably going to
dumb down query-qmp-schema to cover all types, like the reference
manual.

We could create means to mark types "internal use only", and relax
documentation requirements for them.  Of course we better enforce these
are not exposed externally, neither in QMP nor in QOM.

This would let us neglect marking types "internal use only".  If we
don't want that, we could instead require "used by QOM" marks for QOM
use, and treat any type not so marked and also not used by QMP as
internal.