Re: [PATCH] Documentation: amended usages of various (sub)commands

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 28, 2021, 18:32 UTC
Message-ID: <xmqq35wfm8mt.fsf@gitster.g>
In-Reply-To: <de6d56b5-89e4-1e50-1011-0a9b9c46f4d9@gmail.com>

Bagas Sanjaya <bagasdotme@gmail.com> writes:

>>> ...
>> Wait, I expected that this patch touches Documentation/* (as the title implied),
>> but it seems like the patch content is something else (not related).
>> Totally wrong patch submitted here.

Please learn to trim your quotes.

Show 5 quoted lines

> Oops, I don't see that diff above. Sorry for that.
>
> What about this patch title below?:
>
> `Make (sub)command options conform to TD of option parsing`

"Make X conform" has low information contents (especially when nobody knows what the TD is), because nobody would try to make the code worse by making things nonconforming.

    Subject: [PATCH] column, range-diff: downcase option description

    It is customary not to begin the help text for each option given to
    the parse-options API with a capital letter.

    Downcase the first word of some option descriptions for "column"
    and "range-diff".

or something like that?

Even though the guideline for the documentation talks about two things (i.e. not starting with capital and omitting full-stop at the end), the help strings being touched by the patch only have problem with the former, so quoting the guideline in full would not help people understand what is changed and why.