Re: Git migration docs

[Murray Cumming <murrayc murrayc com>]

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.

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.


-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com