Re: [PATCH 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..."

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Mar 18, 2017, 19:16 UTC
Message-ID: <CACBZZX4+HRnb1SV_URqJyxyaeBJ40p_hh_kGEoRj089xJGARHQ@mail.gmail.com>
In-Reply-To: <xmqq7f3m2yph.fsf@gitster.mtv.corp.google.com>

On Sat, Mar 18, 2017 at 8:04 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 12 quoted lines

> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:
>
>>  prefix the first line with "area: " where the area is a filename or
>>  identifier for the general area of the code being modified, e.g.
>>
>> -  . archive: ustar header checksum is computed unsigned
>> -  . git-cherry-pick.txt: clarify the use of revision range notation
>> +  . doc: clarify distinction between sign-off and pgp-signing
>> +  . githooks.txt: improve the intro section
>
> Sorry, but I fail to spot why this is an improvement (it is not
> making things worse, either).

Because...

Show 7 quoted lines

>>  If in doubt which identifier to use, run "git log --no-merges" on the
>>  files you are modifying to see the current conventions.
>>
>> +It's customary to start the remainder of the first line after "area: "
>> +with a lower-case letter. E.g. "doc: clarify...", not "doc:
>> +Clarify...", or "githooks.txt: improve...", not "githooks.txt:
>> +Improve...".

...it makes this subsequent example more succinct and clear, because e.g. "githooks.txt" is shorter than "git-cherry-pick.txt", and "clarify" is obviously a normal looking word which you'd expect to be capitalized after a full stop, but it might take a couple of readings to understand that "unstar" without a hyphen isn't some jargon.