Re: [RFC PATCH 0/6] various documentation bits

From: Junio C Hamano <gitster@pobox.com>
To: Abhishek Kumar <abhishekkumar8222@gmail.com>
Cc: Kenneth Lorber <keni@hers.com>, git@vger.kernel.org
Subject: Re: [RFC PATCH 0/6] various documentation bits
Date: Sun, 17 May 2020 11:39:59 -0700	[thread overview]
Message-ID: <xmqqv9ku5rsw.fsf@gitster.c.googlers.com> (raw)
In-Reply-To: <20200517074258.GA1381@Abhishek-Arch> (Abhishek Kumar's message of "Sun, 17 May 2020 13:12:58 +0530")

Abhishek Kumar <abhishekkumar8222@gmail.com> writes:

> Some general notes about your patch series:
>
> 1. Conventionally, we prefix the first line with "area: " where the area
> is a filename or identifier for general area of the code being modified.
> It's customary to start the remainder of the first line after "area: "
> with a lower-case letter.
>
> For example, your commit titles could have been:
> - doc: tell the glossary about core.hooksPath
> - doc: add bit on extending git to hacking Git
>
> and so on.
>
> Check out SubmittingPatches for more information.

Good suggestion.

> 2. We generally don't have a line like in our patches:
>
>> From Kenneth Lorber <keni@his.com>
>
> Between the author information and the signed-off-by, it's redundant.

Carefully inspect the e-mail header and in-body header ;-)  

The author identity must match the identity written for the
signed-off-by trailer, so the in-body header becomes needed
when the From: e-mail header does not match the true author,
like these patches.

> 3. You could probably join the patches 3 to 6 together. Or maybe
> introduce namespace-collisions.txt in third patch and add
> references in all other files in a new, fourth patch.

Perhaps, but I'd rather not to see a rule that hasn't been applied
even once in the real situation written down like a law.  I'd prefer
to see us gain experience by interacting tool authors on the list
and learn what their concerns and pain-points are.

Thansk.