Improving commit logs

[O'Connor, Daniel]

> On 14 Apr 2016, at 02:26, Eric van Gyzen <vangyzen at FreeBSD.org> wrote:
> On 04/12/16 07:18 PM, O'Connor, Daniel wrote:
>> Some people on IRC were commenting about how commit logs without a 'why' in them are much less useful (both to others and yourself in the future) and how this can be improved in the FreeBSD project.
> I agree emphatically and appreciate your effort.

Great :)

>> 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 same can be said about comments in the code.  You might encourage people to
> answer "why" in comments wherever they think it might be helpful.

I agree, but this suggestion is only for the commit logs - I'm picking my battles :)

>> The how and what can be skipped if they are obvious (it's left as an exercise to the reader to determine what obvious is).
>> Generally speaking *what* is obvious due to the diff itself, the *how* can provide context and is more likely to be useful.
> 
> When deciding what is "obvious", keep this in mind:  When you have been
> neck-deep in this code for several days or weeks, think back to your level of
> understanding when you started working on these changes, and make your decision
> based on that understanding, since that is closer to the level of your audience.

I know, but I don't really think there is a set of rules which will describe it without annoying 80% of the people using it (and different rules will affect a different 80%...)

>> 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 don't let that constrain you, a summary plus more detailed explanation is fine if necessary.
> 
> This wording encourages the whole commit log to be one line as often as
> possible.  A one-line summary is a very good thing and is probably enough for
> most small, simple changes.  However, for changes that are even moderately large
> or complex, I consider the one-liner a summary of the rest of the commit log,
> not of the whole code change.  I would prefer to encourage longer commit logs,
> even to the point of making them too long.  I would rather sift through
> paragraphs of stream-of-consciousness than try to reverse engineer the author's
> mind from a single phrase.

OK, I updated it below.

> It is said that perfection is the enemy of the sufficient.  Although this is
> usually said about code, it applies here, too.  Perhaps you could encourage
> people to write as much as they think is relevant, regardless of their English
> skills or other impediments.

Good idea.

>> As well as including an informative message with each commit you may need to include some additional information.
>> ===== SNIP =====
>> 
>> Does anyone have any (constructive) comments or feedback?
> 
> Thanks for your time and effort on this.

Thanks for the feedback :)

===== 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, and to a lesser degree *how* and *what* was changed.

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 and what can be skipped if they are 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.

Generally speaking *what* is obvious due to the diff itself, the *how* can provide context and is more likely to be useful.

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 =====

--
Daniel O'Connor
"The nice thing about standards is that there
are so many of them to choose from."
 -- Andrew Tanenbaum
GPG Fingerprint - 5596 B766 97C0 0E94 4347 295E E593 DC20 7B3F CE8C