From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47227) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn2Zu-0006dh-G6 for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:54:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bn2Zo-0007EI-MJ for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:54:09 -0400 Received: from mx6-phx2.redhat.com ([209.132.183.39]:44779) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn2Zo-0007EB-Cj for qemu-devel@nongnu.org; Thu, 22 Sep 2016 07:54:04 -0400 Date: Thu, 22 Sep 2016 07:54:03 -0400 (EDT) From: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau Message-ID: <1475206056.671817.1474545243081.JavaMail.zimbra@redhat.com> In-Reply-To: <87h998kwr2.fsf@dusky.pond.sub.org> 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> <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: Markus Armbruster Cc: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau , qemu-devel@nongnu.org Hi ----- Original Message ----- > Marc-Andr=C3=A9 Lureau writes: >=20 > > 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 co= uld > >> > grow again, and there isn't much to learn from that query. > >> > =20 > >> >> Meanwhile, I have a series that touches this code, and will obvious= ly > >> >> 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 wi= ll > >> > 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 t= he > >> 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. >=20 > Misunderstanding? Step (3b) is one step of a reordered series. Let me > repeat the order I proposed: >=20 > 1. Fix existing issues in QAPI schema comments >=20 > 2. Generate documentation from it (not a replacement for > qmp-commands.txt, yet) >=20 > 3. Merge qmp-commands.txt into QAPI schema comments, step by step >=20 > (a) If you only update the QAPI schema comments, qmp-commands.txt > stays intact throughout this work. >=20 > (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. >=20 > 4. Generated documentation now contains everything qmp-commands.txt > contains; delete qmp-commands.txt >=20 > 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. >=20 > 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. >=20 It would have been easier to keep the discussion on the original thread. I = disagreed with this plan: Generating the documentation before the end of 3(b) will also lead to temp= orarily incomplete generated doc, and will conflict with existing qmp-comma= nds.txt. That's why I think the best solution is to go through 3(b) now, collect th= e move in a branch and push it in one go when qmp-commands.txt is empty and= the doc is generated.