Commit message header line

Commit message header line

[Eli Zaretskii]

Header lines such as these:

  Add a warning and a menu.

  Update, improve exposition, add cross references, fix typos.

could be more useful if they included a reference to the feature you
are fixing, in this case Todo Mode.  Otherwise, the header lines are
too generic.

TIA

Re: Commit message header line

[Stephen Berman]

On Fri, 02 May 2014 17:38:09 +0300 Eli Zaretskii <eliz@gnu.org> wrote:

> Header lines such as these:
>
>   Add a warning and a menu.
>
>   Update, improve exposition, add cross references, fix typos.
>
> could be more useful if they included a reference to the feature you
> are fixing, in this case Todo Mode.  Otherwise, the header lines are
> too generic.

Oh dear, sorry about that.  Is it possible to fix that without reverting
and recommitting?  I did this via VC, and thought the commit message
would include the string "calendar/todo-mode.el", since it is in the
ChangeLog entry copied into the commit log buffer, but I see it is not
in the log listing.  But I notice that other log entries do have such a
string; were they explicitly added to the Subject: line in the commit
log buffer, or is that because the Subject: line was left blank so just
the first line of the ChangeLog entry was used?  If so, is that
acceptable practice, or should the Subject: line always be filled in?

Steve Berman

Re: Commit message header line

[Eli Zaretskii]

> From: Stephen Berman <stephen.berman@gmx.net>
> Cc: emacs-devel@gnu.org
> Date: Fri, 02 May 2014 18:06:35 +0200
> 
> On Fri, 02 May 2014 17:38:09 +0300 Eli Zaretskii <eliz@gnu.org> wrote:
> 
> > Header lines such as these:
> >
> >   Add a warning and a menu.
> >
> >   Update, improve exposition, add cross references, fix typos.
> >
> > could be more useful if they included a reference to the feature you
> > are fixing, in this case Todo Mode.  Otherwise, the header lines are
> > too generic.
> 
> Oh dear, sorry about that.  Is it possible to fix that without reverting
> and recommitting?

No.

> I did this via VC, and thought the commit message would include the
> string "calendar/todo-mode.el", since it is in the ChangeLog entry
> copied into the commit log buffer, but I see it is not in the log
> listing.

The ChangeLog entries _are_ in the log message, just not in its first
line:

  Update, improve exposition, add cross references, fix typos.

  * todo-mode.texi: Update, improve exposition, add cross
  references, fix typos.
  (Inserting New Items, Editing Item Headers and Text): Rewrite to
  document new user interface.

However, "bzr log --line" shows only the first line of the log
message, which doesn't mention todo-mode.  I was talking only about
the first (a.k.a. "header") line of the commit message.


> But I notice that other log entries do have such a
> string; were they explicitly added to the Subject: line in the commit
> log buffer, or is that because the Subject: line was left blank so just
> the first line of the ChangeLog entry was used?  If so, is that
> acceptable practice, or should the Subject: line always be filled in?

When there's only one line of ChangeLog entry, it is customary
(though not required) to make it the header line.