Re: [Qemu-devel] [PATCH 03/17] iotests: ask qemu for supported formats

[Thomas Huth]

On 07.06.2018 08:57, Markus Armbruster wrote:
> Thomas Huth <address@hidden> writes:
> 
>> On 05.06.2018 00:40, Eric Blake wrote:
>>> On 06/04/2018 05:34 AM, Thomas Huth wrote:
>>>> On 04.06.2018 09:18, Markus Armbruster wrote:
>>>>> Roman Kagan <address@hidden> writes:
>>>>>
>>>>>> Add helper functions to query the block drivers actually supported by
>>>>>> QEMU using "-drive format=?".  This allows to skip certain tests that
>>>>>> require drivers not built in or whitelisted in QEMU.
>>>>>>
>>>
>>>>>> +    supported_formats=$($QEMU_PROG $QEMU_OPTIONS -drive format=\?
>>>>>> 2>&1 | \
>>>>>
>>>>> Use of '?' to get help is deprecated.  Please use 'format=help', and
>>>>> update your commit message accordingly.
>>>>
>>>> Is it? Where did we document that?
>>>
>>> Hmm, we haven't documented it yet, but it's been that way since commit
>>> c8057f95, in Aug 2012, when we added 'help' as the preferred synonym,
>>> and have tried to avoid mention of '?' in new documentation (as it
>>> requires additional shell quoting).  I'm guessing we'll probably see a
>>> patch from you to start an official deprecation window?
>>
>> I'm using '?' regularly on my own, so don't expect a patch from
>> my side here ;-)
>> Anyway, we still use the question mark in our documentation, e.g.:
>>
>> options
>>
>>     is a comma separated list of format specific options in a name=value 
>> format.
>>     Use -o ? for an overview of the options supported by the used format or 
>> see
>>     the format descriptions below for details.
>>
>> or:
>>
>> -b, --blacklist=list
>>
>>     Comma-separated list of RPCs to disable (no spaces, ‘?’ to list 
>> available RPCs)
> 
> These are bugs, and we need to fix them.
> 
>> So calling it deprecated sounds wrong to me.
> 
> Our intent to deprecate it was pretty clear in commit c8057f95:
> 
>     /**
>      * is_help_option:
>      * @s: string to test
>      *
>      * Check whether @s is one of the standard strings which indicate
>      * that the user is asking for a list of the valid values for a
>      * command option like -cpu or -M. The current accepted strings
> -->  * are 'help' and '?'. '?' is deprecated (it is a shell wildcard
>      * which makes it annoying to use in a reliable way) but provided
>      * for backwards compatibility.
>      *
>      * Returns: true if @s is a request for a list.
>      */
>     static inline bool is_help_option(const char *s)
> 
> Predates today's more formal deprecation policy.  Simpler times.

Sure, but finding such messages in the sources can be quite cumbersome...

> There's no real need to kill off '?', unless it gets in the way of
> steering people towards 'help'.  We should steer them toward 'help',
> because '?' is a trap for insufficiently sophisticated users of
> shell[*].

... and I agree with your points here.

=> I think we need a second list of deprecated feature (maybe we should
call them "legacy features" instead of "deprecated"?), i.e. a list of
features which we don't recommend for new code / scripts anymore, but
which we do not intend to remove via our official deprecation policy any
time soon. Things like "--enable-kvm" / "-no-kvm" or maybe even "-net"
go into the same category.

If you agree, I can try to come up with a patch (should the list go into
qemu-doc.texi or a separate document in the the documentation folder?).

 Thomas