Suffering from CVS mindset

Sun Apr 11 21:17:26 UTC 2010

On Sat, 10 Apr 2010 16:02:34 -0500, Harry Putnam <reader at newsguy.com> wrote:
> New hg user alert!
>
> Maybe I'm just suffering from a lingering CVS mindset, but I'm
> starting to see some problems with commits.
>
> The trial hg repo I'm working with covers a `projects' area where the
> structure is along the lines of a directory with shell script
> experiments, another with perl script experiments, backup
> experimentation.
>
> And onward... just all the little tinkering I do.

FWIW, I'd probably make each project an hg repo of its own.

> If I modify a number of files in the repo, they may not, and probably
> will not have a common thread.  More likely disparate changes not
> related.
>
> Now when I commit some of this, how do I keep up with the changes in
> the log I write.  Is it up to me to manually list the files and tell
> what I changed or why?

I like committing only stuff that fixes an open issue in a bug tracker.
My 'ideal' repository is something like the one Solaris uses whose
commits are all of the general style:

    BUG-NUMBER BUG-SUMMARY-LINE

    LONGER DESCRIPTION WITH MORE INFORMATION ABOUT THE FIX
    ITSELF, E.G. A CONCISE SUMMARY OF THE FINAL CHOICES FOR
    FIXING THIS BUG, COPIED FROM THE BUG DATABASE.

but with extra information about each bug fix commit, e.g. when a commit
fixes bug 17 its log would look like:

    17 /etc/init.d/ntpd should support one off invocations

    When the ntpd init.d script is called with 'onestart' it
    should run ntpd once, but only just once.  The default
    service state for thep ntpd service at boot-time should
    remain unmodified.

If this particular changeset should only affect files in *two* parts of
the repository, the init.d/ntpd and packages/ntpd subdirectories, it can
be generated with one of the following commands:

    hg commit init.d packages
    hg record init.d packages
    hg qnew --git -fe  -I init.d -I packages  bug-17-ntpd-onestart

There are probably other ways to commit all the files of the relevant
bug fix in one changeset.  If I'm missing any, I'm sure someone else
with more hg experience will help me describe them.

> Then when I want to see the log about an individual file in the
> future, the commit log won't have much usefull info unless I've
> written out detailed changes, file names and etc.

The value of the repository history is only the value of what _you_
choose to put in the history.  There is no version control system that
can conjure valuable history out of silly commits like:

    hg commit -m "bug fix"

No matter how hard you try to extract useful historical information out
of a repository with commits like this, you will always find that there
are bits of historical development, notes, rationales, bug information
and other useful stuff that is lost forever.

> Should I have made a separate commit for every file like cvs?

Probably not.  You can still do that, but Mercurial provides a neat and
extensible way of grouping related changes from multiple files into a
coherent set of "changesets".  You should take advantage of this as much
as possible.

> I'm not getting with the idea of commits being repo wide.  Not seeing
> how changes to files are tracked individually... or how to record, or
> review that process.

Repo wide commits make some things easier to reason about.  They also
make some other things much harder to do.

For example with Mercurial it is slightly harder to work on individual
files without cloning the entire repository.  It is still possible
(e.g. by using the "convert" extension and an intermediate repository
that includes only the specific file), but the hoops you have to jump
through to make this work are a bit annoying.

On the other hand, by giving someone else revision 3f924e049136 of your
repository it is a _lot_ easier to verify that everything included in
the snapshot of the project source code is a repeatably consistent copy
of *EVERYTHING* related to that revision.  No more non-sense like "Oh, I
see you have everything but file lib/libfoo/foomagic.c is a stale copy
of revision 1.2, which has already been superseded by about a dozen
commits".

It's all a balance between what you can do easily with CVS and what
Mercurial enables you to do.

> The kind of baloney I see in the log looks nearly useless.
>
>   changeset:   6:317286010708
>   tag:         tip
>   user:        reader   <reader at newsguy.com
>   date:        Sat Apr 10 15:56:16 2010 -0500
>   summary:     I made changes
>
> Doesn't even tell which files were changed, which removed etc etc
> unless I detail every move I made. And include diffs in the log,  I
> won't know poop from looking at the log.
>
> I'm thinking experienced users are doing something very different from
> what I'm doing.

Yes.  For one thing, we *never* write log messages like "In this commit
I changed something".  We generally prefer writing more useful commit
logs, that will probably be at least as useful a few dozen months from
now.  We don't always _have_ this option, but we _prefer_ to have it.

If you don't like log messages like this, just don't write them.  This
is the only way you can be certain they won't look cryptic, content-free
and completely useless a year from now.