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