Re: Git migration docs

[Murray Cumming <murrayc murrayc com>]

On Tue, 2009-01-13 at 14:38 -0500, Kristian Høgsberg wrote: 
> 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.

No, those projects don't write good-enough commit messages and their
generated ChangeLogs are not good enough. The routine has made people
lazy and allowed them to be selfish. Of course there are plenty of
projects that are far worse, regardless of use of git.

Here's a URL of a good-enough ChangeLog:
http://svn.gnome.org/viewvc/gtk%2B/trunk/ChangeLog?view=markup

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. 

> 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.

That's a useful extra. lxr/blame were likewise very useful when we had them 
for GNOME. But I already said that seeing the code changes 
without comments is not good enough.

> 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 think I understand why it happens. But more importantly it _does_ happen 
whether you believe it should or not.

>  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.

A ChangeLog is a different work flow, as I already said.

> > 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.

Good. The correlation between pro-git people and anti-changelog people
has been my number one fear about a migration to git, even more than my
fear of people having difficulty using git.

>   And maybe it's not something that needs to be consistent
> across all modules in GNOME, in which case the point is moot.

Then it's a discussion about what should be recommended in our documentation. 
I favour not changing that part of the documentation just because we are moving to git.

-- 
Murray Cumming
murrayc murrayc com
www.murrayc.com
www.openismus.com