Re: [lmi] 72 chars for git log messages

[Greg Chicares]

On 2016-05-30 12:57, Vadim Zeitlin wrote:
> On Mon, 30 May 2016 12:42:45 +0000 Greg Chicares <address@hidden> wrote:
> 
> GC> On 2016-05-29 22:36, Vadim Zeitlin wrote:
> GC> [...]
> GC> > GC> BTW, I'm going to add a number in square brackets to the first line 
> of
> GC> > GC> any commit message that changes the defect count that 
> 'test_coding_rules'
> GC> > GC> reports.
> GC> > 
> GC> >  Could we please document this somewhere?
> GC> 
> GC> It's documented in 'ChangeLog':
> 
>  Sorry, I don't follow. Does this mean that the git commit messages should
> be written in the same format as the changelog entries?

No, I was only trying to say that it's not completely undocumented:
it is documented, more or less, in the obsolete 'ChangeLog'. That's
by no means ideal, but still better than nothing.

> I don't object to
> this (although for me it would be much more natural to just generate
> changelog from git log then),

I don't think we should maintain 'ChangeLog' any longer. I don't
delete it only because it contains valuable historical information
that's not in `git log`.

But now that we're using git, we should follow git conventions,
which are extremely similar anyway.

> but this doesn't seem to be the case right
> now as there are several minor differences, e.g.
> 
> 1. Width of text: 70 vs 72

I've liberalized that by two characters, because that's a common
git convention.

> 2. Presence (or not) of the period in the first line

The summary line should normally be only imperative-mode sentence,
with no period. (This is how The Economist formats article titles.
I suppose we should just follow their convention completely, using
an internal period if warranted, e.g.:
  Do this. Don't do that
)

> 3. In fact, presence of the summary line at all

Consider:

commit 7c60a41f8afefb52db49f8f4c51a9f9e8ac28f93

Author: Vadim Zeitlin <address@hidden>

Date:   Sun May 1 18:37:22 2016 +0200



    Prefer empty() to 0 == size()



    No real changes, but just simplify the code slightly by using a

    dedicated and more clear method for testing whether a standard

    container is empty.


I think that's pretty close to ideal. The summary line is immediately
clear to anyone who can understand the commit (and that wouldn't be
the place to explain the language to anyone who doesn't know it).
It's followed by one blank line, and then any elaboration in complete
sentences with periods, with no line longer than 72 characters (unless
it's necessary to quote a line of code or give a long URL).

commit 42f470e01c67ccb32b00fcbc967f4971b406b71d

Author: Gregory W. Chicares <address@hidden>

Date:   Mon May 30 19:11:43 2016 +0000



    Refine preferences dialog



    Shorter tab labels. Same border size as other lmi dialogs.


That one's weaker. The summary line should have said more. This
single line would have been better IMO:
    12345678901234567890123456789012345678901234567890123456789012
    Preferences dialog: shorter tab labels; usual lmi border size