Re: [Qemu-devel] [PATCH V6 3/4] qmp, nmi: convert do_inject_nmi() to QObject

[Markus Armbruster]

Anthony Liguori <address@hidden> writes:

> On 02/24/2011 10:20 AM, Markus Armbruster wrote:
>> Anthony Liguori<address@hidden>  writes:
>>
>>    
>>> On 02/24/2011 02:33 AM, Markus Armbruster wrote:
>>>      
>>>> Anthony Liguori<address@hidden>   writes:
[...]
>>>>> Please describe all expected errors.
>>>>>
>>>>>          
>>>> Quoting qmp-commands.hx:
>>>>
>>>>       3. Errors, in special, are not documented. Applications should NOT 
>>>> check
>>>>          for specific errors classes or data (it's strongly recommended to 
>>>> only
>>>>          check for the "error" key)
>>>>
>>>> Indeed, not a single error is documented there.  This is intentional.
>>>>
>>>>        
>>> Yeah, but we're not 0.14 anymore and for 0.15, we need to document
>>> errors.  If you are suggesting I send a patch to remove that section,
>>> I'm more than happy to.
>>>      
>> Two separate issues here: 1. Are we ready to commit to the current
>> design of errors, and 2. Is it fair to reject Lai's patch now because he
>> doesn't document his errors.
>>
>> I'm not commenting on 1. here.
>>
>> Regarding 2.: rejecting a patch because it doesn't document an aspect
>> that current master intentionally leaves undocumented is not how you
>> treat contributors.  At least not if you want any other than certified
>> masochists who enjoy pain, and professionals who get adequately
>> compensated for it.
>>
>> Lead by example, not by fiat.
>>    
>
> http://repo.or.cz/w/qemu/aliguori.git/blob/refs/heads/glib:/qmp-schema.json
>
> I am in the process of documenting the errors of every command.  It's
> a royal pain but I'm going to document everything we have right now.
> It's actually the last bit of work I need to finish before sending
> QAPI out.
>
> So for new commands being added, it would be hugely helpful for the
> authors to document the errors such that I don't have to reverse
> engineer all of the possible error conditions.

The moment this lands in master, you can begin to demand error
descriptions from contributors.  Until then, I'll NAK error descriptions
in qmp-commands.txt.  We left them undocumented there for good reasons:

>>>> Once we have an error design in place that has a reasonable hope to
>>>> stand the test of time, and have errors documented for at least some of
>>>> the commands here, we can start to require proper error documentation
>>>> for new commands.  But not now.

I won't NAK non-normative error descriptions, say in commit messages, or
in comments.  And I won't object to you asking for them.  But I feel you
really shouldn't make it a condition for committing patches.  Especially
not for simple patches that have been on list for months.