Re: [PATCH v2] upload-pack.c: use of parse-options API

From: Junio C Hamano <gitster@pobox.com>
Date: May 19, 2016, 16:46 UTC
Message-ID: <xmqqa8jmknc7.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <431335092.10912437.1463674220365.JavaMail.zimbra@imag.fr>

Matthieu Moy <matthieu.moy@grenoble-inp.fr> writes:

Show 21 quoted lines

> Antoine.Queru@ensimag.grenoble-inp.fr wrote:
>> Option parsing now uses the parser API instead of a local parser.
>> Code is now more compact.
>> Description for -stateless-rpc and --advertise-refs
>> come from the commit (gmane/131517)
>
> Please, use a real commit id instead of a Gmane link.
>
> We don't know how long Gmane will remain up, but a self
> reference from Git's history to itself will always remain valid.
>
> The following alias is handy for this:
>
> [alias]
>         whatis = show -s --pretty='tformat:%h (%s, %ad)' --date=short
>
> In your case it would allow writing: 
>
> Description for --stateless-rpc and --advertise-refs is taken
> from commit 42526b4 (Add stateless RPC options to upload-pack,
> receive-pack, 2009-10-30).

Good suggestion; a real question may be how you went from $gmane/131517 to 42526b4 (I vaguely recall that you have and publish a database of sort; this would be a good place to advertise it ;-).

Show 10 quoted lines

>
>> diff v1 v2:
>
> We usually say "diff" to refer to an actual diff. I'd write "changes since v1" here.
>
>> +		OPT_BOOL(0, "stateless-rpc", &stateless_rpc,
>> +			 N_("may perform only a single read-write cycle with stdin and stdout")),
>
> It's weird to define what an option does with "may". It's a
> property of --stateless-rpc, but does not really define it.

If this "may" were to express "The program might or might not do this, and we do not know what it would do until we try", then it indeed would be weird. But the way the word "may" was used in 42526b4 is "the program is ALLOWED to do only a single exchange".

I agree that the phrasing is bad, in the sense that it can be misread as a non-definition; perhaps

    quit after a single request/response exchange

or something?