From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:59432) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn3ID-0007zd-2Y for qemu-devel@nongnu.org; Thu, 22 Sep 2016 08:39:58 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bn3I9-0007RF-Tk for qemu-devel@nongnu.org; Thu, 22 Sep 2016 08:39:57 -0400 Received: from mx5-phx2.redhat.com ([209.132.183.37]:56039) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn3I9-0007Qu-KK for qemu-devel@nongnu.org; Thu, 22 Sep 2016 08:39:53 -0400 Date: Thu, 22 Sep 2016 08:39:52 -0400 (EDT) From: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau Message-ID: <1507086107.680200.1474547992616.JavaMail.zimbra@redhat.com> In-Reply-To: <87y42kf778.fsf@dusky.pond.sub.org> References: <20160913130209.695-1-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> <1475206056.671817.1474545243081.JavaMail.zimbra@redhat.com> <87y42kf778.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 ----- > >> >> 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 > >> >> >> 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.h= tml > >> >> > > >> >> > 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 t= o > >> >> 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 t= he > >> > QAPI schema, command documentation regresses temporarily. Tolera= ble, > >> > but needs to be explained in commit messages. Your choice. > >> > > >> > Isn't that what this series is doing? it moves the remaining doc fro= m > >> > qmp-commands.txt to the schema. > >>=20 > >> Misunderstanding? Step (3b) is one step of a reordered series. Let m= e > >> 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. Tolerabl= e, > >> 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 pic= k. > >> 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 > > temporarily incomplete generated doc, and will conflict with existing > > qmp-commands.txt. >=20 > Having incomplete new documentation (getting less incomplete in each > commit) conflict with incomplete old documentation (getting more > incomplete) is no worse than having old documentation getting more > incomplete. In both cases, we go through an intermediate state with > flawed documentation. Not if we merge the move in one go, as I propose. Don't you think it's cleaner if we first move the documentation in one plac= e before we generate yet another incomplete doc? >=20 > > That's why I think the best solution is to go through 3(b) now, collec= t > > the move in a branch and push it in one go when qmp-commands.txt is em= pty > > and the doc is generated. >=20 > If you prefer to do it this way, I suggest to post everything at once, > because I won't bother reviewing any of step 3 before step 2 for the > reasons I explained above. I don't want to see review of the step 2 > invalidate all our review work on step 3. I fail to see how generating the doc could invalidate moving the documentat= ion in the schema. Indeed, we may want to tweak the documentation style for some reason, but t= hat's irrelevant for now, all we should focus on is having the doc in one p= lace before doing further work with it.=20