From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:36055) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bnKyf-0005Wh-6b for qemu-devel@nongnu.org; Fri, 23 Sep 2016 03:32:59 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bnKyb-0005ca-07 for qemu-devel@nongnu.org; Fri, 23 Sep 2016 03:32:56 -0400 Received: from mx1.redhat.com ([209.132.183.28]:43698) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bnKya-0005c3-Md for qemu-devel@nongnu.org; Fri, 23 Sep 2016 03:32:52 -0400 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (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 53A81C0528A0 for ; Fri, 23 Sep 2016 07:32:51 +0000 (UTC) From: Markus Armbruster 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> <1507086107.680200.1474547992616.JavaMail.zimbra@redhat.com> Date: Fri, 23 Sep 2016 09:32:48 +0200 In-Reply-To: <1507086107.680200.1474547992616.JavaMail.zimbra@redhat.com> (=?utf-8?Q?=22Marc-Andr=C3=A9?= Lureau"'s message of "Thu, 22 Sep 2016 08:39:52 -0400 (EDT)") Message-ID: <87wpi3xe8v.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 ----- >> >> 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 [...] >> >> >> >> 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. Toler= able, >> >> > but needs to be explained in commit messages. Your choice. >> >> > >> >> > Isn't that what this series is doing? it moves the remaining doc fr= om >> >> > 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. Tolerab= le, >> >> 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 interestin= g: >> >> step 1, 2 and some of 3a or 3b, depending on which alternative you pi= ck. >> >> 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 threa= d. 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 pl= ace before we generate yet another incomplete doc? At this time, I'm 100% focused on ease of review and saving your and your reviewers' time. Once we got review under control, I'm happy to talk about whether another order or some squashing makes more sense for the permanent Git record. >> > That's why I think the best solution is to go through 3(b) now, colle= ct >> > the move in a branch and push it in one go when qmp-commands.txt is e= mpty >> > 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 > documentation in the schema. > > Indeed, we may want to tweak the documentation style for some reason, > but that's irrelevant for now, all we should focus on is having the > doc in one place before doing further work with it. Arguing further about the perfect order feels like a waste of time. You're free to post this in the order you feel is right. If it differs from the order that I feel is right for my review, then please post the whole thing, so I can review it effectively.