Improving commit logs

[Steven Hartland]

On 14/04/2016 04:52, O'Connor, Daniel wrote:
>> On 14 Apr 2016, at 13:18, Glen Barber <gjb at FreeBSD.org> wrote:
>>
>> On Thu, Apr 14, 2016 at 01:14:46PM +0930, O'Connor, Daniel wrote:
>>>> On 14 Apr 2016, at 13:13, Glen Barber <gjb at FreeBSD.org> wrote:
>>>> I absolutely agree with you that a guide on this will be beneficial.
>>>> Sorry if my reply was taken any other way.
>>>>
>>>> If I had a genie in a bottle, my three wishes would be:
>>>>
>>>> 1) Better commit messages that address the "what";
>>>> 2) Better explanation on the "why";
>>> Huh interesting, I definitely would pick 2 before 1 but I can see
>>> what you mean for a lot of commits (especially to 30 year old cruft
>>> filled esoterica)
>> When writing release notes, for example, the "what" is generally more
>> useful than the "why."  In other words, the end user does not generally
>> care *why* something changed, but they want to know *what* changed.
> That's a good point, my original version was written more in the mind of someone who understands the code already but as you (and ngie) point out there are other consumers of the code.
>
> ===== SNIP =====
> This section contains some suggestions and traditions for how commit logs are formatted and what they should contain.
>
> A commit log should explain *why* a commit has taken place, *what* was changed and to a lesser degree *how*.
>
> The why of a commit message is absolutely critical to allow other people (including your future self) to understand the reason a change was made.
>
> The how can be skipped if it is obvious - it's left as an exercise to the reader to determine what obvious is. You should try and step into the mind set of someone who is familiar with FreeBSD but not focussed on the particular area you have committed to. What is obvious now can be obtuse in a few months when you or someone else is reviewing the code to track down issues. The commit logs are used by more people that just other developers - they are used to develop tests and release notes as well.
>
> Generally speaking *how* is obvious due to the diff itself assuming you have used enough comments, but clever tricks should probably be explained (or commented in the code).
>
> Due to the use of git and use of svn blame it is highly desirable to have a 1 line summary of the commit, however do not think this means you only need a 1 line summary. Write the full log first, then summarise it if possible. If you aren't sure, err on the side of a longer rather than shorter commit message.
>
> As well as including an informative message with each commit you may need to include some additional information.
>
> ===== SNIP =====
I definitely agree!

I've found myself on a number of occasions sending emails across to 
people asking for clarification on why things have been changed in order 
to better understand areas I'm less familiar with. Providing official 
guidance is always good IMO :)

     Regards
     Steve