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

["Daniel P. Berrangé" <berrange@redhat.com>]

On Thu, Jun 07, 2018 at 09:50:41AM +0200, Thomas Huth wrote:
> 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.

I don't see much point to be honest. If --enable-kvm works for the user
and we're not intending to removal it, I don't see why they should care
about using something else instead.  The other thing might have a more
flexible syntax, but if they don't need those extra features it really
doesn't matter. IOW, I think it is sufficient to just document all the
options that exist, and when documenting them simply make a note inline
that a particular option is merely  syntax suger for an alternative
option.

Regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|