Re: Referring to revisions in the git future.

[Eric S. Raymond]

Stefan Monnier <address@hidden>:
> > About summary lines, a reminder: Please don't write the traditional
> > GNUish run-on change comment with a semi-infinite number of bulleted
> > items in it any more.
> 
> That's your opinion, but the convention we still use here (and don't
> just recommend but *request* people to follow) is the GNU ChangeLog format.

That's fine - for ChangeLogs.  But if you write run-on text without summary
lines *in comments*, you will make it more difficult for other programmers
to get a view of what you are doing through the DVCS tools.  Look at
a gitk display to see what I mean.

In the DVCS world, comments that don't have proper summary lines
impose friction costs. You shouldn't do that to other developers.  If
GNU conventions "request" you to impose such friction costs, it's GNU
conventions that are the problem and must change.

> > We're no longer in CVS-land, commits are cheap,
> 
> Don't know yet about Git, but I can assure you that in Bzr-land, commits
> are not cheap (things like "bzr merge", "bzr annotate" and many others
> have time complexities that depend on the number of commits).

Yes, git commits are cheap.  This was a hard requirement for the
kernel-dev workflow, which is very merge-intensive.

> > make them fine-grained.
> 
> Fine-grained or not is irrelevant.  What they should be is logical/coherent.
> Your recent 20 or so single-line commits which all have the same summary
> line is the perfect example of what should *not* be done.

Heh.  And, of course, you don't understand that the exact reason I did
this was the ChangeLog conventions - I was trying to be a good soldier
and make changesets in which content changes were properly grouped
with their ChangeLog entries, and this meant in practice I could not
generally allow a commit to touch multiple directories containing
ChangeLogs.  Even if it was trivial in all of them.

The underlying problem here is that ChangeLog entries and changeset
comments contest each other for authority over the same kinds of
metadata.  Eventually, ChangeLogs are bound to lose, because they're a
half-assed simulation of changeset comments without the actual
changesets.  In the mean time,  they're going to require a lot
of ceremony and duplicative effort and lead to avoidable mistakes.

ChangeLogs were a reasonable adaptation to file-oriented VCSes, but
their time is gone.  It's 2014. Changeset commit logs have been
a thing for a decade now; we should start acting like we know that.
-- 
                <a href="http://www.catb.org/~esr/";>Eric S. Raymond</a>