From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:39252) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZXag4-0002lZ-G3 for qemu-devel@nongnu.org; Thu, 03 Sep 2015 16:00:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ZXag1-0007N5-0i for qemu-devel@nongnu.org; Thu, 03 Sep 2015 16:00:08 -0400 Received: from e35.co.us.ibm.com ([32.97.110.153]:60623) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ZXag0-0007KT-QO for qemu-devel@nongnu.org; Thu, 03 Sep 2015 16:00:04 -0400 Received: from /spool/local by e35.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Thu, 3 Sep 2015 14:00:01 -0600 Received: from b03cxnp08025.gho.boulder.ibm.com (b03cxnp08025.gho.boulder.ibm.com [9.17.130.17]) by d03dlp02.boulder.ibm.com (Postfix) with ESMTP id 7B6553E40041 for ; Thu, 3 Sep 2015 13:59:59 -0600 (MDT) Received: from d03av04.boulder.ibm.com (d03av04.boulder.ibm.com [9.17.195.170]) by b03cxnp08025.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id t83Jwt4r39583834 for ; Thu, 3 Sep 2015 12:58:55 -0700 Received: from d03av04.boulder.ibm.com (loopback [127.0.0.1]) by d03av04.boulder.ibm.com (8.14.4/8.14.4/NCO v10.0 AVout) with ESMTP id t83Jxx1a023802 for ; Thu, 3 Sep 2015 13:59:59 -0600 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable From: Michael Roth In-Reply-To: <87egifl9nj.fsf@blackfin.pond.sub.org> References: <1438703896-12553-1-git-send-email-armbru@redhat.com> <20150901184026.18566.39890@loki> <55E5F898.6040304@redhat.com> <20150901202348.18566.60300@loki> <87io7t42t2.fsf@blackfin.pond.sub.org> <20150902162156.11972.58160@loki> <87r3mfyhty.fsf@blackfin.pond.sub.org> <55E859A5.9060807@redhat.com> <20150903155932.11972.308@loki> <87egifl9nj.fsf@blackfin.pond.sub.org> Message-ID: <20150903195953.10296.47286@loki> Date: Thu, 03 Sep 2015 14:59:53 -0500 Subject: Re: [Qemu-devel] [PATCH RFC v3 30/32] qapi: New QMP command query-schema for QMP schema introspection List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Markus Armbruster Cc: kwolf@redhat.com, berto@igalia.com, qemu-devel@nongnu.org Quoting Markus Armbruster (2015-09-03 12:01:20) > Michael Roth writes: > = > > Quoting Eric Blake (2015-09-03 09:31:01) > >> On 09/03/2015 03:26 AM, Markus Armbruster wrote: > >> >> > >> >> I think we need to be careful that these descriptions are not > >> >> interpreted by clients as an alternative to the more-specific > >> >> constraints in the QAPI schema though. 'query-schema' seems > >> >> a bit misleading in that regard, it appears to be more like > >> >> 'query-schema-encoding' in function. But not sure it's worth > >> >> renaming or anything so long as the documentation is clear. > >> > = > >> > You have a point: "schema" can mean two related, yet different thing= s. > >> > There's the QAPI schema, and there's the QMP (the wire protocol) sch= ema. > >> > QMP introspection is about the latter, not the former. > >> > = > >> > If we want to avoid the ambiguity, we could call the command > >> > query-qmp-schema or something. > >> > = > >> > Renaming query-schema now might confuse people coming from my KVM Fo= rum > >> > talk slightly, but if we can agree on a better name, let's do it. > >> = > >> I'm okay if you want to use 'query-qmp-schema'; it's a bit longer, but > >> more precise, and doesn't cause too much grief to change the name at > >> this point in the game. > > > > I'm also okay with this. It avoids confusion down that road if we > > ever introduced, say, a query-ber-schema or something. > > > > I have some minor reservations: I think query-qmp-schema-mapping or > > query-qmp-schema-encoding, i.e. "give me information on how the > > [QAPI] schema maps to the QMP wire protocol", is more correct. > > query-qmp-schema reads like "give me the complete schema for the > > QMP wire protocol", which makes it more tempting to treat the > > result as a complete schema, rather than a component of what's > > defined by the QAPI schema. > = > Well, it *is* the schema for the QMP wire protocol. Which happens to be > mechanically derived from the QAPI schema. True, but the separation from QMP wire schema and QAPI interface schema wouldn't be clear to most users. It would be fairly tempting/reasonable for the author of a QMP client to assume the "QMP schema" was the definitive source for how a client should interact with QEMU without realizing or finding the need to reference the QAPI schema for more specific constraints (like integer ranges). I'm somewhat harping on this because that's exactly the misconception I had when I first looked at this series, which is why the loss of information like integer ranges didn't seem acceptable to me initially. But I don't really have a problem with query-qmp-schema, the naming comments are more a suggestion of the sort of confusion we should try to clear up in the accompanying documentation. > = > > But in all likelihood trying to cram all that information into the > > command name would probably just be confusing to most, so a simpler > > name with clear documentation seems reasonable. > = > I think query-qmp-schema hits the sweet spot between "ambiguous because > it's too short" and "too long because we tried to make it unambiguous". > I'll adopt it in v5. > = > Regarding clear documentation: we don't have to get it perfect in the > initial commit, but I'm of course happy to address review of RFC PATCH > v4 in v5. > = Thanks, sounds reasonable to me.