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