ChangeLogs

[Daniel J Sebald]

I've back-tracked through the Maintainers dicussion list about choosing a new version-control-system, Mercurial or Git, of last year to get up to speed on things.  (I missed first time around.)  I've also investigated some of the recent distributed VCSs.  I have some general comments and then replies to John specific points below regarding ChangeLogs.

First, general comments:

I see the advantages of distributed VCS and atomic changesets.  CVS always did feel sort of klunky leaving me a bit exhausted trying to organize things.  The top three DVCSs (bzr, hg, git) all work easily enough.

Bazaar does not restore deleted files when doing 'uncommit'.  Must do an extra command for that.  Mercurial does restore the deleted files of a 'rollback'.  I prefer that.

All three DVCSs will 'rollback', 'uncommit', 'revert' a changeset, but in all cases the files don't have the same date as when they were commited.  I wish the date was retained.  Perhaps that doesn't make sense in the DVCS paradigm, but for convenience when working with the local copy only that would be nice.  Having the files touched as a result of rolling back might cause recompiling.  Plus dates of files contain
information that keeps my mind organized when coding.

As for Mercurial, one rollback is kind of limiting.  Being able to edit comments
(i.e., "recommit") *as far back as the last clone/push/pull* would be very
convenient.  So many times I've looked back at a comment and wanted to correct
or better state something.  Note that I said as far back as the last
clone/push/pull.  Once a changeset is propogated, modifying comments isn't good
practice.  So long as it is a local copy, however, greater flexibility would be
nice.  (With that in mind, even one allowed "rollback" is too much if something
has been pushed/pulled/cloned.)

Git seems to have a more robust method of branching and maintaining old changesets
compared to others.  It is sort of the way I'd imagine a branch working.  (Hard to
program, too, I imagine.)

Mercurial's advantage is syntax cleanliness and intuitiveness; same for automating
things enough, but not too much.  And that may be enough in and of itself.

Case in point.  I've tried some Git examples.  According to documentation, one has
to add the file to a staging area for every change.  My thought is, "I added this
file already, why must I do it again?"  I'm perplexed, with all the Git users
complaints about CVS, why build a system that essentially requires the same amount
of effort to place every file into a staging area first?  Yes, there is the '-a'
option.  But that is sort of an extraneous thing if 95% of the time it is used.
A '-a' is a long pinky stretch on the keyboard, and consequently has higher
likelihood of error... requiring a long hand movement to 'backspace'.

Git 'diff' will display an empty file when there are no changes.  Mercurial just
returns to the command line.  Again, Hg just seems to be more efficient in terms
of keystrokes.

Now, allow me to address some of John's comments.


John W. Eaton wrote:
> On 18-Jan-2009, Thorsten Meyer wrote:
> 
> | I also like this solution. Yet I am still a little confused about
> what it means in detail. Let me | try a little recap. The proposal
> seems to be this: |  - We no longer write ChangeLog entries |  -
> Instead write commit messages like in John's example: | |     one
> line summary | |     * file1.cc (function): What changed. |
> (other_function): Other change. |     * file2.cc (function): Another
> change. | |  - The old ChangeLog files are renamed to
> ChangeLog.number |  - ChangeLog files are generated using |      hg
> log --style=changelog |    with releases of octave. | | I have a few
> questions: |  - how to we credit contributions of people who do not
> push to savannah themselves in the future?
> 
> When you create the changeset, you can use the
> 
> --user "user name <email at address>"

Save some effort, define this in the .hgrc file.


> option to commit, qnew, or qrefresh.  That way the specified user
> name shows up in the commit log instead of your ID.  I also recomment
> using the --currentdate option to qnew or qrefresh so the timestamp
> on the patch is updated each time you refresh a patch in the MQ.  I
> have this as a default in my .hgrc file:
> 
> [defaults] qnew = --currentdate --currentuser qrefresh =
> --currentdate
> 
> |    I think we should add the name of the contributor to the commit
> message (unless |    contributor=committing person).
> 
> I think all that needs to be done is for you to use the --user option
>  when commiting a change.
> 
> |  - Should we also add the creation date of the patch?
> 
> I don't see that this date is important.

There was debate about the date to use:  Time of changeset creation?  Or time
of push into canonical repository?  I'd prefer the latter and notice I used
the word canonical.  I can see the logic of changeset creation date having
more meaning in a DVCS where atomic changesets can be moved about.  But John
has set up a canonical repository where I think ChangeLog has meaning (and I
would miss I think).  The ChangeLog should have the date when the changeset
was moved into the canonical repository.

Here is what I think would be the best solution, and if it isn't a Mercurial
feature it might be worthwhile for one of us to make a feature request to the developers.

One should be able to build a "template comment file", say .hgtemplate or
something.  The default format is not something like:

----

HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: --
HG: user: sebald at local.localdomain
HG: branch 'default'
HG: changed junk.txt
HG: changed junk2.txt


Why not allow the user to define a template with a few simple codes that
will pop up a commit message like:

----
First line is displayed in 'hg log'.

2008-02-06  Daniel J. Sebald  <d.s at somewhere.org>

	* junk.txt: 
        * junk2.txt:
HG: Enter commit message.  Lines beginning with 'HG:' are removed.
HG: --
HG: user: sebald at local.localdomain
HG: branch 'default'
HG: changed junk.txt

Just fill in the missing comments and it is formatted with a consistent
ChangeLog entry (the date is current date, no tab/space inconsistency)
that could be sorted with some Hg plugin.  Perhaps Hg would shreek at such
an idea.

Dan