Re: Git migration docs

[Kristian Høgsberg <krh redhat com>]

On Tue, 2009-01-13 at 19:52 +0100, Murray Cumming wrote:
> On Tue, 2009-01-13 at 09:36 -0500, Kristian Høgsberg wrote:
> > On Tue, 2009-01-13 at 00:22 +0100, Santi Béjar wrote:
> > >  * ChangeLog: This is one of the most useful files for a developer to
> > > keep up to date - it lists all the changes that a given  project has
> > > undergone. In GNOME it is generally of the following form:
> > > {{{
> > > YYYY-MM-DD  Joe Bloggs <joe bloggs gnome org>
> > > 
> > > 	* filename.c: Use gtk_dialog instead of deprecated gnome-dialog.
> > > 	Fixes #878372.
> > > }}}
> > 
> > ChangeLog was useful back when with CVS there was no way to see what
> > changed in a project and what files was involved with a specific commit.
> > With git this is a lot less useful as git tracks the changes as atomic
> > commits and you can easily browse the history using git log, cgit,
> > giggle, gitk or many other tools.  In fact, when branching and merging,
> > the ChangeLog gets in the way and always causes merge conflicts.
> > 
> > Historically, the commit message has been of little use and all the
> > attention has gone to the ChangeLog entry and it's an integral part of
> > many peoples workflow.  We just need to apply the same discipline and
> > attention to writing a good commit message instead.  And part of the
> > GNOME migration process should probably be coming up with a make dist
> > hook that GNOME modules can add to dump the git log into a ChangeLog
> > file when making tarballs.
> 
> People who discard ChangeLogs in favour of commit messages all end up
> writing bad commit messages, just because of the changed routine. There
> are no good real-world examples, even for projects that generate a
> ChangeLog in tarballs. They generally don't describe what changed,
> where, how, or why. Seeing the actual code changes without explanation
> isn't the same, just as code without comments is less useful. It's lazy
> and it's selfish, keeping other developers from working on your code. 
> 
> It also leads to less code review because people write the message when
> committing, instead of before. With a ChangeLog, people make corrections
> as they go through the diff, looking at each thing they have to comment
> in the ChangeLog. It also makes it very difficult to correct a
> ChangeLog/commit message later.

I don't see many references or much reasoning here, just assertions.
How is it not possible for a disciplined developer, who's trained to
commit small, self contained changes and document them in a ChangeLog to
apply that same discipline to writing a good commit message instead?
Look to the kernel, cairo, the X.org modules for examples of projects
that successfully use the VCS commit messages and no ChangeLog.  I don't
think it's justified or necessary to call the people who work on these
projects lazy and selfish.

I can see where you're coming from; traditionally the tools (CVS and
SVN, even though it does have atomic commits) haven't given you much
incentive to write a good commit message and the ChangeLog has been the
best and fastest way to read up on what has happened recently or years
ago in a project.  With git, however, there's a huge return on letting
the tool associate a meaningful description of the change with the
committed data: tools can visualize the log of changes for web, local
tools or email, you can search the log for a specific string or bug
number and once found, jump straight to the commit in question and
cherry pick or revert it.

But fundamentally, I just don't understand the claim that a developer
that has the discipline to write good ChangeLog entries suddenly fall
apart and starts doing git commit -a -m "uh, changed stuff".  I know
that there are many projects out there that don't use ChangeLog and have
terrible commit messages, but that doesn't imply that not using a
ChangeLog sucks all discipline out of your developers.  It's all about
habits and work flows, there's nothing inherently magic in a ChangeLog.

> The changelog vs. no-changelog argument has very little to do with the
> svn v. git argument. Please have that argument separately if you must.

Sure; there is some overlap in that git and the associated tools make it
easier to browse the log and inspect the changes for a given commit, and
also that git makes branching and merging much easier and useful, in
which case the ChangeLog becomes a common source of merge conflicts.

But it's certainly not an argument that needs to be resolved before we
can switch, and we're also not trying to add it as a rider to the DVCS
migration.  And maybe it's not something that needs to be consistent
across all modules in GNOME, in which case the point is moot.

cheers,
Kristian