From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:40742) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn22E-000135-3a for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:19:23 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bn228-0005Fi-LB for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:19:21 -0400 Received: from mx1.redhat.com ([209.132.183.28]:45928) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn228-0005Fa-BL for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:19:16 -0400 Received: from int-mx11.intmail.prod.int.phx2.redhat.com (int-mx11.intmail.prod.int.phx2.redhat.com [10.5.11.24]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id E6BBDC05AA5B for ; Thu, 22 Sep 2016 11:19:15 +0000 (UTC) From: Markus Armbruster References: <20160913130209.695-1-marcandre.lureau@redhat.com> <20160913130209.695-16-marcandre.lureau@redhat.com> <1592483129.530259.1474488068217.JavaMail.zimbra@redhat.com> <87lgyknx8e.fsf@dusky.pond.sub.org> <1403625254.632846.1474533952810.JavaMail.zimbra@redhat.com> Date: Thu, 22 Sep 2016 13:19:13 +0200 In-Reply-To: <1403625254.632846.1474533952810.JavaMail.zimbra@redhat.com> (=?utf-8?Q?=22Marc-Andr=C3=A9?= Lureau"'s message of "Thu, 22 Sep 2016 04:45:52 -0400 (EDT)") Message-ID: <87h998kwr2.fsf@dusky.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau Cc: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau , qemu-devel@nongnu.org Marc-Andr=C3=A9 Lureau writes: > Hi > > ----- Original Message ----- >> Marc-Andr=C3=A9 Lureau writes: >>=20 >> > Hi >> > >> > ----- Original Message ----- >> >> On 09/13/2016 08:01 AM, Marc-Andr=C3=A9 Lureau wrote: >> >> > Signed-off-by: Marc-Andr=C3=A9 Lureau >> >> > --- >> >> > docs/qmp-commands.txt | 29 ----------------------------- >> >> > qapi-schema.json | 13 +++++++++++++ >> >> > 2 files changed, 13 insertions(+), 29 deletions(-) >> >> >=20 >> >>=20 >> >> > +++ b/qapi-schema.json >> >> > @@ -1011,6 +1011,19 @@ >> >> > # Returns: @MigrationParameters >> >> > # >> >> > # Since: 2.4 >> >> > +# >> >> > +# Example: >> >> > +# >> >> > +# -> { "execute": "query-migrate-parameters" } >> >> > +# <- { "return": { >> >> > +# "decompress-threads": 2, >> >> > +# "cpu-throttle-increment": 10, >> >> > +# "compress-threads": 8, >> >> > +# "compress-level": 1, >> >> > +# "cpu-throttle-initial": 20 >> >> > +# } >> >> > +# } >> >> > +# >> >> > ## >> >> > { 'command': 'query-migrate-parameters', >> >> > 'returns': 'MigrationParameters' } >> >>=20 >> >> The example lacks 'cpu-throttle-increment', 'tls-creds', and >> >> 'tls-hostname'; do we want to take this opportunity to touch it up? >> > >> > I suggest to put a [...] in the returned example, as this example could >> > grow again, and there isn't much to learn from that query. >> >=20=20 >> >> Meanwhile, I have a series that touches this code, and will obviously >> >> create a merge conflict for whoever gets in second: >> >> https://lists.gnu.org/archive/html/qemu-devel/2016-09/msg01946.html >> > >> > Yes, the more we wait to review the series, the more conflicts we will= get. >> > There is still over 100 patches to go, I'll send the next 30. >>=20 >> We suggested restructuring the series, and you liked the idea with the >> alternative step (3b), not (3a). Would it make sense to repost the >> beginning of the multi-part monster in that form before moving on to the >> next part? > > 3. Merge qmp-commands.txt into QAPI schema comments, step by step > > (b) If you delete qmp-commands.txt section as you cover them in the > QAPI schema, command documentation regresses temporarily. Tolerable, > but needs to be explained in commit messages. Your choice. > > Isn't that what this series is doing? it moves the remaining doc from qmp= -commands.txt to the schema. Misunderstanding? Step (3b) is one step of a reordered series. Let me repeat the order I proposed: 1. Fix existing issues in QAPI schema comments 2. Generate documentation from it (not a replacement for qmp-commands.txt, yet) 3. Merge qmp-commands.txt into QAPI schema comments, step by step (a) If you only update the QAPI schema comments, qmp-commands.txt stays intact throughout this work. (b) If you delete qmp-commands.txt section as you cover them in the QAPI schema, command documentation regresses temporarily. Tolerable, but needs to be explained in commit messages. Your choice. 4. Generated documentation now contains everything qmp-commands.txt contains; delete qmp-commands.txt This way, the first part contains everything that's really interesting: step 1, 2 and some of 3a or 3b, depending on which alternative you pick. The remaining parts are just more of 3a or 3b, plus the trivial step 4 in the last one. I proposed this to get the interesting review of step 2 out of the way early, and before we tire ourselves out on the not-so-interesting but necessary review of step 3.