From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42395) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjoiN-0006V8-5x for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:29:40 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bjoiH-0008Ke-CK for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:29:34 -0400 Received: from mx3-phx2.redhat.com ([209.132.183.24]:50302) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjoiH-0008Ia-4K for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:29:29 -0400 Date: Tue, 13 Sep 2016 10:29:27 -0400 (EDT) From: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau Message-ID: <1315953386.299567.1473776967487.JavaMail.zimbra@redhat.com> In-Reply-To: <87y42v5241.fsf@dusky.pond.sub.org> References: <20160913130209.695-1-marcandre.lureau@redhat.com> <87y42v5241.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 00/30] Move qapi documentation to schema (part 1/5) 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, > > > > The QAPI documentation is currently done in two places, the json > > schema and a more human-friendly text file. The goal is to avoid > > duplication and to generate friendly versions from the schema (pdf, > > man etc). Thus, all documentation should be moved to the schema. > > > > In order to facilitate the review, the documentation move has been > > splitted, and is going to sent by chunks of ~30 patches. This way it > > should take about 5 series to complete (~150 patches). I suggest that > > the qapi maintainers (Markus/Eric) compile the reviewed patches in a > > branch and merge upstream in one go (either merging move commits or > > not) when the series complete and the documentation is finally > > generated to avoid an in-between state. > > > > The wip branch with all the pending patches: > > https://github.com/elmarco/qemu/commits/qapi-doc >=20 > Ah, now I understand why you asked whether to post everything! The > "move FOO doc to schema" patches make no sense until the very end of the > full branch, when you actually generate documentation from the schema. >=20 > Perhaps you could structure like this: >=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 > Getting to this structure with option (3b) could be as simple as > reordering your branch. 3(a) makes it hard to check that everything has been moved properly, while = removing 3(b) makes it clear what is removed and adjusted in the correspond= ing schema doc, and by the end of 3(b) it's clear that nothing has been lef= t behind. Generating the documentation before the end of 3(b) will also lead to tempo= rarily incomplete generated doc, and will conflict with existing qmp-comman= ds.txt. That's why I think the best solution is to go through 3(b) now, collect the= move in a branch and push it in one go when qmp-commands.txt is empty and = the doc is generated.