Re: Git migration docs

[Mathias Hasselmann <mathias hasselmann gmx de>]

Am Donnerstag, den 15.01.2009, 18:22 +0100 schrieb Murray Cumming:
> On Thu, 2009-01-15 at 11:16 -0600, Jason D. Clinton wrote:
> > On Tue, Jan 13, 2009 at 2:42 PM, Murray Cumming <murrayc murrayc com> wrote:
> > > On Tue, 2009-01-13 at 14:38 -0500, Kristian Høgsberg wrote:
> > > I don't think you can provide a URL of a generated-from-commit-messages
> > > ChangeLog that is good enough, though people often asserts that one
> > > exists, and the tools cannot tell me what a human being told me in a
> > > good ChangeLog, because the tools cannot read minds.
> > 
> > This is just FUD. Here is a counter examples of a changelog which is
> > generated from commit messages[1]
> 
> Below is a snippet of that Changelog (which is annoyingly in a tarball
> instead of at an actual URL). Surely you can see how that's less useful,
> and less readable, than the GTK+ ChangeLog?
> 
> To spell it out, it doesn't mention what was changed in what part
> (usually, what function) in what file, and why. You might not find that
> useful, but I do, and it's our de-facto convention.
> 
> Some of the commits also don't mention real develoer names. I also find
> that information useful.

After having the same discussion with Murray some time ago, I've
developed the following process to conveniently maintain ChangeLog files
with git:

     1. Install git-merge-changelog from gnulib[1] and tell git about it
        via .gitattributes file. The header of git-merge-changelog.c
        explains the necessary steps.
     2. When ready to commit, open the ChangeLog file in my current
        editor.
     3. Invoke my mkcl macro to prepare a ChangeLog entry.
     4. Fill the ChangeLog entry.
     5. Save the ChangeLog file.
     6. Call my custom commit script[2] which invokes "git commit" using
        the first entry of the ChangeLog file as commit message. The
        email address of that entry and the leading tabs are stripped of
        course when creating the commit message.

To get pretty output with git log, my ChangeLog entries all start with a
summarizing paragraph:

        2009-01-15  Mathias Hasselmann  <mathias hasselmann gmx de>
        
        	Explain the readers of this list how my ChangeLog entries
        	look like.
        
        	* src/maman_bar.c (MananBarPrivate, maman_bar_init(),
                  maman_bar_foo()): Drop foo field and track blub in
                  blah table now.
        
This works pretty well and is much more convenient than typing "git
commit" and trying to create a ChangeLog like commit message with
$EDITOR.

Currently I still plan to add a similar (optional) feature to giggle's
commit dialog.

Only downside of this approach: With git's awesome capabilities for
local commits, local branches and interactive rebase and so on I've got
quite used to micro commits. Those micro commits have the sad side-
effect that my initial pragraph already explains the entire commit,
so that for the single files there is nothing more to say than "See
summary".

So maybe we should just drop the old habit of creating large self
contained commits which require exhaustive ChangeLog entries: Micro
patches that focus on just one change are much easier to review.

Ciao,
Mathias

[1] http://git.savannah.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
[2] http://taschenorakel.de/gitweb/?p=scmtools;a=blob;f=commit
-- 
Mathias Hasselmann <mathias hasselmann gmx de>
Personal Blog: http://taschenorakel.de/mathias/
Openismus GmbH: http://www.openismus.com/