From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 04 Mar 2022 00:27:28 GMT
Subject: Re: [PATCH v3 2/3] CodingGuidelines: hint why we value clearly written log messages
Message-ID: <xmqqv8wu5zpr.fsf@gitster.g>
In-Reply-To: <YiFYQBWBVq/HQULM@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

>> + - Log messages to explain your changes are as important as the
>> +   changes themselves.  Clearly written code and in-code comments
>> +   explain how the code works and what is assumed from the surrounding
>> +   context.  The log messages explain what the changes wanted to
>> +   achieve and why the changes were necessary (more on this in the
>> +   accompanying SubmittingPatches document).
>> +
>
> One thing not listed here, that I often hope to find from the commit
> message (and don't), is "why we did it this way instead of <other way>".
> I am not sure how to phrase it in this document, though. Maybe:
>
>   The log messages explain what the changes wanted to achieve, any
>   decisions that were made between alternative approaches, and why the
>   changes were necessary (more on this in blah blah)
>
> Or maybe "...whether any alternative approaches were considered..." fits
> the form of the surrounding sentence better.

Quite valid observation.

Documentation/SubmittingPatches::meaningful-message makes a note on
these points, and the above may want to be more aligned to them.

Patches welcome, as these have long been merged to 'master/main'.

Thanks.