Re: [Qemu-devel] [PATCH 15/30] qmp-commands: move 'query-migrate-parameters' doc to schema

[Eric Blake]

On 09/22/2016 06:54 AM, Marc-André Lureau wrote:

>> 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.
>>

> 
>  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.

Incomplete generated doc is fine, if the commit message calls it out
that upcoming patches will fix the gaps (after all, that's what 3(b)
says to do).  And I tend to agree with Markus that reviewing the
generator first, rather than after we've burned ourself out looking over
lots of individual commands, will give us a chance to make sure the
generator is sane (and may even have some minor impacts to HOW we move
documentation over, if we end up tweaking the .json files to make the
generator easier to manage).

>  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.

As it is, I already made comments about the first batch where you were
mixing in fixes (step 1) with doc motion, but failed to mention it in
the commit message.  And where Markus has already argued that making
those fixes on their own as a prerequisite is a bit cleaner than forcing
the review of step 3 to be more complex.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature