Header lines of commit messages

Header lines of commit messages

[Eli Zaretskii]

Commit messages such as the one below are not helpful:

    revno: 100645
    author: Carsten Dominik <carsten.dominik@gmail.com>
    committer: Romain Francoise <romain@orebokech.com>
    branch nick: trunk
    timestamp: Sat 2010-06-26 11:53:06 +0200
    message:
      Cherry-pick commit 8bd9308 from the org-mode Git repository.

      2010-06-26  Carsten Dominik  <carsten.dominik@gmail.com>

	    * org-agenda.el (org-agenda-goto-calendar): Do not bind obsolete
	    variables.

	    * org.el (calendar): Require calendar now on top level in org.el
	    and define aliases to new variables when needed.
	    (org-read-date, org-goto-calendar): Do not bind obsolete
	    variables.

The header line that summarizes the commit conveys useless
information.  It should state the essence of the change instead, so
that people who use "bzr log --line" will be able to grasp the purpose
of the change without looking at the full text.  The info about the
commit number, if it's deemed to be important, should be in the body
of the commit message, not in the header line.

TIA

Re: Header lines of commit messages

[Romain Francoise]

Eli Zaretskii <eliz@gnu.org> writes:

> The header line that summarizes the commit conveys useless
> information.  It should state the essence of the change instead, so
> that people who use "bzr log --line" will be able to grasp the purpose
> of the change without looking at the full text.

For changes that are made directly in Emacs, yes.

In this case, org-mode is maintained outside Emacs and I'm just
merging a fix from the original repository. If we followed the logic
that the header line should always accurately describe the change,
we wouldn't allow commits like these either:

100593: Romain Francoise 2010-06-12 Synch with Gnus trunk.
100575: Katsumi Yamaoka 2010-06-10 [merge] Synch with Gnus trunk.
100541: Katsumi Yamaoka 2010-06-07 [merge] Synch with Gnus trunk.
100498: Katsumi Yamaoka 2010-06-02 [merge] Synch with Gnus trunk.
100428: Ryan Yeske 2010-05-24 rcirc update.
100277: Katsumi Yamaoka 2010-05-14 [merge] Synch with Gnus trunk.
100255: Katsumi Yamaoka 2010-05-13 [merge] Synch with Gnus trunk.
100243: Katsumi Yamaoka 2010-05-12 [merge] Synch with Gnus trunk.
100228: Katsumi Yamaoka 2010-05-11 [merge] Synch with Gnus trunk.
100214: Katsumi Yamaoka 2010-05-10 [merge] Synch with Gnus trunk.
100180: Katsumi Yamaoka 2010-05-07 [merge] Synch with Gnus trunk.
100160: Katsumi Yamaoka 2010-05-06 [merge] Synch with Gnus trunk.
99989: Katsumi Yamaoka 2010-04-22 [merge] Synch with Gnus trunk:
99727: Katsumi Yamaoka 2010-03-23 [merge] Synch with Gnus trunk
98224: Katsumi Yamaoka 2009-10-19 Synch with Gnus trunk:
97798: Katsumi Yamaoka 2009-09-28 Synch with Gnus trunk.
97797: Katsumi Yamaoka 2009-09-28 Synch with Gnus trunk.
96612: Katsumi Yamaoka 2009-07-17 Synch with Gnus trunk:
96020: Katsumi Yamaoka 2009-06-08 Synch with Gnus trunk:
83292: Michael Albinus 2007-12-23 Sync with Tramp 2.1.12.
81049: Michael Albinus 2007-10-10 Sync with Tramp 2.1.11.
78711: Michael Albinus 2007-07-22 Sync with Tramp 2.1.10.
74948: Michael Albinus 2006-12-30 Sync with Tramp 2.0.55.
72532: Michael Albinus 2006-08-29 Sync with Tramp 2.0.54.

Instead we'd ask people to replay each logical change from the
original repository in Emacs, and we'd always have meaningful header
lines.

> The info about the commit number, if it's deemed to be important,
> should be in the body of the commit message, not in the header
> line.

It's a merge. Where it came from is just as important as what it
does, and the fact that it's a single commit rather than a bunch of
unrelated changes doesn't really change anything.

In an ideal world Emacs would be using Git, and org-mode, Gnus, ERC
and others would just be submodules pointing to a given branch of
the original repository. Then doing such a merge would not lose
information. But we're stuck with bzr + patch.

Re: Header lines of commit messages

[Eli Zaretskii]

> From: Romain Francoise <romain@orebokech.com>
> Date: Sat, 26 Jun 2010 15:33:56 +0200
> Cc: emacs-devel@gnu.org
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> > The header line that summarizes the commit conveys useless
> > information.  It should state the essence of the change instead, so
> > that people who use "bzr log --line" will be able to grasp the purpose
> > of the change without looking at the full text.
> 
> For changes that are made directly in Emacs, yes.
> 
> In this case, org-mode is maintained outside Emacs and I'm just
> merging a fix from the original repository.

I don't see why this is different.

> If we followed the logic that the header line should always
> accurately describe the change, we wouldn't allow commits like these
> either:
> 
> 100593: Romain Francoise 2010-06-12 Synch with Gnus trunk.
> 100575: Katsumi Yamaoka 2010-06-10 [merge] Synch with Gnus trunk.
> 100541: Katsumi Yamaoka 2010-06-07 [merge] Synch with Gnus trunk.
> 100498: Katsumi Yamaoka 2010-06-02 [merge] Synch with Gnus trunk.

For merges that bring in a lot of unrelated changes, this is
acceptable, because there's no practical way to come up with a
meaningful header line.  But in your case, you cherry-picked a single
change set that can be summarized with a short header line.

> the fact that it's a single commit rather than a bunch of
> unrelated changes doesn't really change anything.

I think it does: describing this single commit with a short meaningful
text is possible and reasonably easy.

> In an ideal world Emacs would be using Git, and org-mode, Gnus, ERC
> and others would just be submodules pointing to a given branch of
> the original repository. Then doing such a merge would not lose
> information. But we're stuck with bzr + patch.

No, in an ideal world, org-mode, Gnus, ERC, etc. would be using
Bazaar, and Bazaar would be fast enough for them to have no reason to
use Git.

In any case, I don't see a reason to punish Emacs for using Bazaar.
(Your text sounds like saying: you decided to use Bazaar, so now you
get to pay for it.)

But that has nothing to do with the issue at hand.  I'm sorry that you
disagree with me, because it means more meaningless commit messages
are to come.

Re: Header lines of commit messages

[Stephen J. Turnbull]

Romain Francoise writes:
 > Eli Zaretskii <eliz@gnu.org> writes:
 > 
 > > The header line that summarizes the commit conveys useless
 > > information.

I would phrase that "the headline conveys the information that
thinking about this commit is useless to Emacs maintainers."<wink>
Seriously, you've been describing your information overload in other
contexts.  Yes, as a member of the project, it's important to have
some idea of who's active, but the details would just be overload.

 > In this case, org-mode is maintained outside Emacs and I'm just
 > merging a fix from the original repository.

I suggest that you use the word "synch" for this purpose, as Gnus
does.  I think the presence of the commit is a convenience, myself,
but it's strictly speaking not necessary in the headline if it's
present in the body of the commit notice.

 > In an ideal world Emacs would be using Git, and org-mode, Gnus, ERC
 > and others would just be submodules pointing to a given branch of
 > the original repository.

This is actually somewhat unlikely, both for technical and social
reasons.  The technical reason is that a git submodule points to a
commit, not to a branch.

The social reason is that almost certainly Emacs will insist on
control of content of releases, and it's possible that in pre-release
branches the Emacs version of org-mode will not correspond exactly to
any commit in the upstream repository, and surely not to the tip of
any actively developed branch.

It's not a big deal from your point of view, but technically it means
that the view in logs and $VCS viewers would probably be just as
complicated.

Re: Header lines of commit messages

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: Eli Zaretskii <eliz@gnu.org>,
>     emacs-devel@gnu.org
> Date: Sun, 27 Jun 2010 00:04:07 +0900
> 
> Romain Francoise writes:
>  > Eli Zaretskii <eliz@gnu.org> writes:
>  > 
>  > > The header line that summarizes the commit conveys useless
>  > > information.
> 
> I would phrase that "the headline conveys the information that
> thinking about this commit is useless to Emacs maintainers."<wink>
> Seriously, you've been describing your information overload in other
> contexts.

Exactly.  That is why seeing "cherry-pick commit ABCDEF" means I need
to read the whole commit message, i.e. waste my time, whereas "[merge]
Do not bind obsolete variables." tells it all without any additional
effort.

> Yes, as a member of the project, it's important to have
> some idea of who's active, but the details would just be overload.

Sorry, I'm not following.  I didn't want to see the author of the
change, just its essence.

Re: Header lines of commit messages

[Stephen J. Turnbull]

Eli Zaretskii writes:
 > > From: "Stephen J. Turnbull" <stephen@xemacs.org>
 > >  > Eli Zaretskii <eliz@gnu.org> writes:
 > >  > 
 > >  > > The header line that summarizes the commit conveys useless
 > >  > > information.
 > > 
 > > I would phrase that "the headline conveys the information that
 > > thinking about this commit is useless to Emacs maintainers."<wink>
 > > Seriously, you've been describing your information overload in other
 > > contexts.
 > 
 > Exactly.  That is why seeing "cherry-pick commit ABCDEF" means I need
 > to read the whole commit message, i.e. waste my time, whereas "[merge]
 > Do not bind obsolete variables." tells it all without any additional
 > effort.

You're missing the point.  Romain and the org-mode community are
responsible for org-mode most of the time, until it becomes Stefan's/
Yidong's baby in the run-up to a release.  Either way, it should not
affect any of the things you are interested in, so you just don't want
to know.  You want your eyes to glide right over "org-mode synch to
git commit ABCDEF" just as it does over "Gnus synch."  Life is too
short to even think about that stuff.  Put it this way: what could
Romain have written there that would cause you to want to read the
whole commit message?

If you really *do* want to know about irrelevant commits, I don't
understand why you find it acceptable that Gnus doesn't rebase its
synchs into the mainline.  After all, Gnus contains message-mode, and
that does affect your life since message-mode is proposed as a
replacement for RMail's composition mode, a replacement you don't yet
consider acceptable.  So what exactly is happening in Gnus is in fact
relevant to you; even I know that.  Why don't you complain about that?
Presumably because *there are too many irrelevant commits* compressed
into those merges, and you are forced to the conclusion that reading
them would be a waste of your time, and a waste of the committer's
time to rebase them onto the mainline.

Well, the org-mode synch is just as irrelevant.

 > > Yes, as a member of the project, it's important to have
 > > some idea of who's active, but the details would just be overload.
 > 
 > Sorry, I'm not following.  I didn't want to see the author of the
 > change, just its essence.

You think you do, but that's just an unproductive habit, as shown by
the fact that you don't have a problem with the Gnus merge messages.

Also, by "who" I mean which subprojects, not which developers.

Re: Header lines of commit messages

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen@xemacs.org>
> Cc: romain@orebokech.com,
>     emacs-devel@gnu.org
> Date: Sun, 27 Jun 2010 02:08:37 +0900
> 
> Romain and the org-mode community are responsible for org-mode most
> of the time, until it becomes Stefan's/ Yidong's baby in the run-up
> to a release.  Either way, it should not affect any of the things
> you are interested in, so you just don't want to know.  You want
> your eyes to glide right over "org-mode synch to git commit ABCDEF"
> just as it does over "Gnus synch."  Life is too short to even think
> about that stuff.

You are assuming too much, and/or think about your habits when you
talk about mine.  Please don't decide for me what is relevant and what
isn't.  My interests in Emacs development are more than just bidi and
MS-DOS, you know.  In particular, I happen to be a happy used of the
Org mode, and therefore my interests in what gets committed to the
Emacs repository by Org maintainers are not just theoretical.

In the Gnus case, I'd prefer more meaningful headers as well, but it's
hard to ask for that when a large body of unrelated changes is
delivered to Emacs at once.

More generally, people who commit changes should not ass-u-me too much
when they reason about the importance of clear and concise commit
messages and their summary header lines.  They will never be able to
second-guess the interests of those who will be reading those
messages.  So it is best to format and word them as if the reader were
genuinely interested in the package being modified and privy to its
features.

> Put it this way: what could Romain have written
> there that would cause you to want to read the whole commit message?

I already suggested such a header: "Do not bind obsolete variables."

> If you really *do* want to know about irrelevant commits, I don't
> understand why you find it acceptable that Gnus doesn't rebase its
> synchs into the mainline.

Because I'm too old to fight Quixotic battles.  And because people who
do the job should have some leeway in determining how far they want to
go towards the project to which they contribute.  If Stefan and Yidong
can live with what Gnus maintainers do when they synch, so can I.

> After all, Gnus contains message-mode, and that does affect your
> life since message-mode is proposed as a replacement for RMail's
> composition mode, a replacement you don't yet consider acceptable.
> So what exactly is happening in Gnus is in fact relevant to you;
> even I know that.  Why don't you complain about that?

You again want to decide for me what is interesting.  And now you even
decide what I should complain about.  Please don't.

> Presumably because *there are too many irrelevant commits* compressed
> into those merges, and you are forced to the conclusion that reading
> them would be a waste of your time, and a waste of the committer's
> time to rebase them onto the mainline.
> 
> Well, the org-mode synch is just as irrelevant.

Not this one.  See its ChangeLog entry.  And maybe re-read what I
wrote in this thread, because I already responded to all these
arguments.

Re: Header lines of commit messages

[Stephen J. Turnbull]

Eli Zaretskii writes:

 > You are assuming too much, and/or think about your habits when you
 > talk about mine.  Please don't decide for me what is relevant and what
 > isn't.

OK, you win.  Your preferences are what they are, and I don't really
care what they are, or to try to change them, in fact.

I do, however, think that catering to them would be a bad idea, for
the reasons I have given.

Re: Header lines of commit messages

[Ted Zlatanov]

On Sat, 26 Jun 2010 21:16:51 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

EZ> In the Gnus case, I'd prefer more meaningful headers as well, but it's
EZ> hard to ask for that when a large body of unrelated changes is
EZ> delivered to Emacs at once.

Katsumi Yamaoka has been doing the synchronization so far.  Let him and
the other Gnus developers know if there's a problem with the
synchronization log messages.

I plan to eventually set up a more automatic synchronization method.

>> If you really *do* want to know about irrelevant commits, I don't
>> understand why you find it acceptable that Gnus doesn't rebase its
>> synchs into the mainline.

EZ> Because I'm too old to fight Quixotic battles.  And because people who
EZ> do the job should have some leeway in determining how far they want to
EZ> go towards the project to which they contribute.  If Stefan and Yidong
EZ> can live with what Gnus maintainers do when they synch, so can I.

Sorry, I am not clear on the problem, though it's probably obvious to
you.  Can you explain what's the problem and what we can do on the Gnus
side to remedy it?

Thanks
Ted

Re: Header lines of commit messages

[Eli Zaretskii]

> From: Ted Zlatanov <tzz@lifelogs.com>
> Date: Wed, 30 Jun 2010 13:36:13 -0500
> Cc: ding@gnus.org
> 
> On Sat, 26 Jun 2010 21:16:51 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 
> 
> EZ> In the Gnus case, I'd prefer more meaningful headers as well, but it's
> EZ> hard to ask for that when a large body of unrelated changes is
> EZ> delivered to Emacs at once.
> 
> Katsumi Yamaoka has been doing the synchronization so far.  Let him and
> the other Gnus developers know if there's a problem with the
> synchronization log messages.

As long as you are committing to the Emacs repository many unrelated
changes, there really is no way of making the commit messages more
useful.  But at least in several cases, it looks like the committed
changes belong to a single changeset.  Examples:

    revno: 100593
    committer: Romain Francoise <romain@orebokech.com>
    branch nick: trunk
    timestamp: Sat 2010-06-12 19:26:40 +0200
    message:
      Synch with Gnus trunk.
      * gnus-util.el (gnus-date-get-time): Move up before first use.
    ------------------------------------------------------------
    revno: 100575 [merge]
    committer: Katsumi Yamaoka <yamaoka@jpl.org>
    branch nick: trunk
    timestamp: Thu 2010-06-10 05:54:25 +0000
    message:
      Synch with Gnus trunk.
      (gnus-mime-buttonized-part-id): New internal variable.
      (gnus-article-edit-part): Bind it to make last part that is substituted
       or deleted visible.
      (gnus-mime-display-single): Buttonize part of which id equals to
       gnus-mime-buttonized-part-id.
    ------------------------------------------------------------
    revno: 100564 [merge]
    committer: Katsumi Yamaoka <yamaoka@jpl.org>
    branch nick: trunk
    timestamp: Thu 2010-06-10 00:31:03 +0000
    message:
      Synch with Gnus trunk.
      2010-06-10  Dan Christensen  <jdc@uwo.ca>
       * gnus-util.el (gnus-user-date): Use gnus-date-get-time.
       (gnus-dd-mmm): Use gnus-date-get-time.
       * gnus-sum.el (gnus-thread-latest-date): Use gnus-date-get-time and
       simplify logic.
       (gnus-summary-limit-to-age): Use gnus-date-get-time.
       (gnus-sort-threads): emit message if gnus-sort-threads-loop used.
    ------------------------------------------------------------

For such changes, it would be more useful if the first line of the
commit message summarized the change, instead of saying just "Synch
with Gnus trunk".  That would allow to, e.g., find the merge which
introduced some specific change in Gnus by just looking at the output
of "bzr log --line", which shows only those first lines from the
commit messages.

> I plan to eventually set up a more automatic synchronization method.

Thanks.  For that, I hope the original commit message would become the
commit message in the Bazaar repository.

> >> If you really *do* want to know about irrelevant commits, I don't
> >> understand why you find it acceptable that Gnus doesn't rebase its
> >> synchs into the mainline.
> 
> EZ> Because I'm too old to fight Quixotic battles.  And because people who
> EZ> do the job should have some leeway in determining how far they want to
> EZ> go towards the project to which they contribute.  If Stefan and Yidong
> EZ> can live with what Gnus maintainers do when they synch, so can I.
> 
> Sorry, I am not clear on the problem, though it's probably obvious to
> you.  Can you explain what's the problem and what we can do on the Gnus
> side to remedy it?

Only what I ask above regarding the first line of the commit messages.

Re: Header lines of commit messages

[Ted Zlatanov]

On Thu, 01 Jul 2010 00:08:51 +0300 Eli Zaretskii <eliz@gnu.org> wrote: 

EZ> As long as you are committing to the Emacs repository many unrelated
EZ> changes, there really is no way of making the commit messages more
EZ> useful.  But at least in several cases, it looks like the committed
EZ> changes belong to a single changeset.  Examples:
...
EZ> For such changes, it would be more useful if the first line of the
EZ> commit message summarized the change, instead of saying just "Synch
EZ> with Gnus trunk".  That would allow to, e.g., find the merge which
EZ> introduced some specific change in Gnus by just looking at the output
EZ> of "bzr log --line", which shows only those first lines from the
EZ> commit messages.

Thanks for explaining.  The Gnus developers will try to make these
commits look better in the --line format and we'll see if we can make
the synchronization happen for every commit instead of batched.

Ted