Re: Commit practices

["Stephen J. Turnbull" <stephen@xemacs.org>]

Richard Stallman writes:

 > In effect, the suggestion here is that we abandon the idea
 > of useful readable info associated by the VCS with each file.

I don't understand why you expect that effect.  Certainly, there are
developers who, given the opportunity, will commit megapatches, and
associate them with megalogs, which are unreadable.  This is a social
problem.  Lash them with a wet noodle or chmod their cvs to 0644 until
they mend their evil ways.

However, all of the dVCS (distributed VCS) advocates strongly advocate
"coherent changesets", ie, keeping all the changes needed to implement
a fix or a feature in one changeset, and keeping others out.  Eg, do
you object to

----------------------------------------------------------------
2007-12-30  Stephen J. Turnbull  <stephen@xemacs.org>

Resolve bug where bar() frotzes instead of bazzing in a
quuxotic context.

* foo.h (bar): Add baz argument to prototype.

* foo.c (bar): Implement new baz argument, which when non-NULL
causes bar() to baz rather than frotz.

* quux.c (a, b, c, d, e): Update calls to bar() with bar = NULL.
(f): Update call to bar() with appropriate baz value.
----------------------------------------------------------------

as a common commit notice for foo.h, foo.c, and quux.c?  I find this
style of log, cross-referencing the declaration, the implementation,
and the already fixed uses, very useful.  But in the "coherent
changeset" style something like

----------------------------------------------------------------
2007-12-30  Stephen J. Turnbull  <stephen@xemacs.org>

* foo.h (glorp): Fix typo in comment.
----------------------------------------------------------------

would *not* be acceptable if merged into the above.  Is this close to
what you want?

I grant that a change such as merging the Emacs-Unicode branch will
not fit into this model.  But I personally don't think it fits well
into the one-notice-per-file model, either, as the cross-referencing
will be missing, and the logs, if at all detailed, will be very long
anyway.  Big merges are just horrid to create useful logs for.

As a practical matter, dVCSes enable this style by making frequent
commits easy.  Coherent changesets are easier to write good logs for.
Some dVCSes even provide facilities allowing selection of which hunks
to use in the commit, making it possible to omit gratuitous typo fixes
from the main commit.  Such a feature could be made generic (in Emacs)
by adding a front-end based on diff-mode.

In projects I observe where VCSes more modern than CVS are in use, it
is typically the case that static ChangeLog files have been abandoned
in favor of histories generated by the VCS, and nobody misses the
files.  (NB: I'm not telling you what to think, I'm simply presenting
an observation.)