Re: Summarizing the purpose of a change.

[Giorgos Keramidas <keramida@ceid.upatras.gr>]

On Sat, 21 Nov 2009 11:11:15 +0200, Eli Zaretskii <eliz@gnu.org> wrote:
>Karl Fogel <kfogel@red-bean.com> writes:
>>> In many projects, there is a convention of summarizing the purpose of a
>>> change in one or two sentences at the start of the log entry.  This makes
>>> the rest of the log entry (and the change itself) easier to understand.
>>
>> And if possible, make the summary not "1 or 2" sentences, but a single
>> not-to-long line, such as you'd use for an email Subject: header.
>
> I suspect pointing to the relevant discussion on emacs-devel, or to a
> bug number (if there is any) would be a lesser burden.

Yes, when there *is* a bug number this is useful.

A short summary in the first line of each commit is often useful for
other changes too; changes that are not necessarily bug fixes.

For example, Bazaar has a "--line" option that can display long lists of
changesets by showing a single-line summary for each commit.  In a small
sample repository with the following history:

: keramida@kobe:/tmp/koko$ bzr log
: ------------------------------------------------------------
: revno: 3
: committer: Giorgos Keramidas <keramida@kobe>
: branch nick: koko
: timestamp: Sat 2009-11-21 13:19:31 +0200
: message:
:   bug #27 -- add a '.localnet' suffix to the default 'foo' name
:
:   The installation scripts can set the default domain name to a more
:   sensible value, but there are bits of the installer code that may
:   have to read 'foo' before DNS, NIS or some other resolver scheme
:   is up and running.  So add a default '.localnet' domain part to
:   the name of 'foo', and let the resolver code replace it with the
:   real domain name later.
: ------------------------------------------------------------
: revno: 2
: committer: Giorgos Keramidas <keramida@kobe>
: branch nick: koko
: timestamp: Sat 2009-11-21 13:18:24 +0200
: message:
:   bug #19 -- 'foo' always displays a short name
:
:   We need the full name of the 'foo' utility here.  Shortening the name
:   to something less chatty can be done by the GUI utilities.
: ------------------------------------------------------------
: revno: 1
: committer: Giorgos Keramidas <keramida@kobe>
: branch nick: koko
: timestamp: Sat 2009-11-21 13:18:07 +0200
: message:
:   Add foo
: keramida@kobe:/tmp/koko$

the bzr(1) utility can show a short summary of all the changes in just 3
lines of output:

: keramida@kobe:/tmp/koko$ bzr log --line
: 3: Giorgos Keramidas 2009-11-21 bug #27 -- add a '.localnet' suffix to the default 'foo' name
: 2: Giorgos Keramidas 2009-11-21 bug #19 -- 'foo' always displays a short name
: 1: Giorgos Keramidas 2009-11-21 Add foo
: keramida@kobe:/tmp/koko$

The format of the commits logs I used in the sample repository make the
short log summary more useful because their first line includes enough
context about the intent of each change.