On Mon, Oct 25, 2021 at 12:24 AM Markus Armbruster <arm...@redhat.com> wrote:
> The next commit will add feature flags to enum members. There's a > problem, though: query-qmp-schema shows an enum type's members as an > array of member names (SchemaInfoEnum member @values). If it showed > an array of objects with a name member, we could simply add more > members to these objects. Since it's just strings, we can't. > > I can see three ways to correct this design mistake: > > 1. Do it the way we should have done it, plus compatibility goo. > > We want a ['SchemaInfoEnumMember'] member in SchemaInfoEnum. Since > changing @values would be a compatibility break, add a new member > @members instead. > > @values is now redundant. In my testing, output of > qemu-system-x86_64's query-qmp-schema grows by 11% (18.5KiB). > > We can deprecate @values now and drop it later. This will break > outmoded clients. Well-behaved clients such as libvirt are > expected to break cleanly. > > 2. Like 1, but omit "boring" elements of @member, and empty @member. > > @values does not become redundant. @members augments it. Somewhat > cumbersome, but output of query-qmp-schema grows only as we make > enum members non-boring. > > There is nothing to deprecate here. > > 3. Versioned query-qmp-schema. > > query-qmp-schema provides either @values or @members. The QMP > client can select which version it wants. There is no redundant > output. > > We can deprecate old versions and eventually drop them. This will > break outmoded clients. Breaking cleanly is easier than for 1. > > While 1 and 2 operate within the common rules for compatible > evolution apply (section "Compatibility considerations" in > docs/devel/qapi-code-gen.rst), 3 bypasses them. Attractive when > operating within the rules is just too awkward. Not the case here. > > This commit implements 1. Libvirt developers prefer it. > > Deprecate @values in favour of @members. Since query-qmp-schema > compatibility is pretty fundamental for management applications, an > extended grace period is advised. > > Signed-off-by: Markus Armbruster <arm...@redhat.com> > Reviewed-by: Eric Blake <ebl...@redhat.com> > Tested-by: Peter Krempa <pkre...@redhat.com> > Acked-by: Peter Krempa <pkre...@redhat.com> > Reviewed-by: John Snow <js...@redhat.com>
