Re: [PATCH/GSoC 3/3] Nousage message in error

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 24, 2016, 16:23 UTC
Message-ID: <xmqqh9fvalpm.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAFZEwPN2vp+zOMdGY51LwNpgNcYxsGD4GBXHNOA8_qJ8vtE5OQ@mail.gmail.com>

Pranit Bauva <pranit.bauva@gmail.com> writes:

> A general convention followed by git users it to write the commit
> message as "What he did to the code?" rather than "What problem was
> there in the code?"

It is OK for other projects to adopt a different convention, but The project convention here is different.

We tend to write our log message like this in this order:

 - Explain relevant behaviour and code structure in the current code
   to refresh memory of readers to help them understand the next two
   items better.  This paragraph is optional and you see it only in
   difficult patches.

 - Desribe the problem.  What the end user would do and what she
   sees in response to it, why that is not a good outcome, and what
   would be a better outcome.  For a patch to only improve code,
   replace "the end user" with "other codepaths that interact with
   the code being changed".

 - Explain the approach to implement a better outcome.  This
   paragraph is optional and you see it only in patches that
   implement tricky solutions.

 - Describe the solution, as if you are giving orders to the
   maintainers to change the code this way and that way.