Commit netiquette.

[Óscar Fuentes]

It would be a Good Thing (TM) to explicitly set good practices for
commits. People is accustomed to CVS and following those customs with
changeset-based systems like Bazaar is counterproductive. VC history,
like code, is written once but read a thousand times, so it is worth to
write it with some care. A correct VC history can be exploited by tools
that traverses it doing useful things (i.e. `bisect').

Let's look at one example:

revno: 99513
committer: Mark A. Hershberger <address@hidden>
branch nick: local
timestamp: Wed 2010-02-17 16:39:21 -0500
message:
  2010-02-17  Mark A. Hershberger  <address@hidden>
  
        * vc-bzr.el: fix typo in Known Bugs section.
  
        * isearch.el (isearch-update-post-hook): New hook
        (isearch-update): Use the new hook.
modified:
  lisp/ChangeLog
  lisp/isearch.el
  lisp/vc-bzr.el

The Committer used the full Changelog entry as the commit message, so on
interfaces that just shows the first line of the commit (like the
emacs-diffs mailing list or the output of `bzr log --short' or `qlog')
you see

2010-02-17  Mark A. Hershberger  <address@hidden>

which is hardly indicative of the change.

Ideally, the commit message should be made of a first line indicating
the *purpose* of the change plus a longer text with a more complete
explanation. Usually the changelog entry is good enough as the complete
explanation (without the changelog's entry header!). If the changelog
entry contains only one line and it is descriptive of the purpose of the
change, it can be used as the commit message. In this case, it is
preferable to remove the leading asterisk because it just adds noise and
some text-based tools use asterisks for denoting nodes on the DAG.

Another very important thing is to realize that a changeset-based VCS
presents a view of the progress as a series of atomic steps that changes
the content of the project. This is good because it allows to
unambiguously establish the state of the project at certain point and
identify the steps that caused that state. For this to be really useful,
it is very important to not divide a change among several commits
(i.e. by doing a commit for each edited file) and to not mix different
changes on the same commit, as the case above.