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

[Markus Armbruster <armbru@redhat.com>]

Thomas Huth <thuth@redhat.com> writes:

> On 07.06.2018 08:57, Markus Armbruster wrote:
>> Thomas Huth <thuth@redhat.com> 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 <rkagan@virtuozzo.com> 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?).

I'm not sure it's worthwhile.

The boundary between "deprecated with intent to remove" and "deprecated
without such intent" is going to be a fuzzy one.  Could it be a useful
one anyway?

Formal deprecation is largely for the benefit of people writing software
that interfaces with QEMU.  They really need to know in advance, and
they are well advised to treat either kind of deprecation as "should
move to the replacement interface in an orderly manner".

If you use QEMU manually, it's easier to just keep using stuff until
it's gone, then look for the replacement.