Re: [Monotone-devel] monotone Hacking

[Julio M. Merino Vidal]

On Sep 11, 2007, at 1:12 PM, Stephen Leake wrote:

> Richard Levitte <address@hidden> writes:
>
> > In message <address@hidden> on  
> > Tue, 11 Sep 2007 12:22:43 +0200, "Julio M. Merino Vidal"  
> > <address@hidden> said:
> >
> > jmmv84> Using plain text messages will make one think twice before
> > jmmv84> doing that, because he'll have to explain *why* he is
> > jmmv84> committing that at once.
> >
> > I totally agree with that.  There are numerous messages saying that
> > the programmer fiddle with this and that function, created a new one,
> > removed an old one, but NOT ONE WORD about the overall change, its
> > intention or its reasons.  Basically, that makes for crap
> > documentation.
>
> On the other hand, that is the way we typically work. I often notice
> "little things" while I'm working on one "big thing". Would it be
> better to _not_ fix them? Or do one commit for each little thing?

I'm not saying that they do not to be fixed.  They indeed have, but  
those *unrelated* changes have to be committed separately.  The  
cleaner the changesets, the easier it is to later cherrypick/merge/ 
review/understand specific changes.

> Documentation belongs in .texi files, not in commit messages. Commit
> messages should help you find when a change occured, and give
> pointers/hints about why, but the real reasons should be in more
> stable form.

Agreed; but ChangeSets are not a design document either.  Commit  
messages should explain the reason behind a change or an outline of  
it, not what the change exactly did (because the latter is already  
available in the diff and the change's meta-data!).

Of course, if that change is important, it should be documented  
somewhere else to prevent what you mention below.

> Otherwise, you can get oscillations; "changed to a linked list because
> it's faster on Windows", "changed to a red-black tree because it's
> faster on Gentoo" etc. If those comments were in a design file, it
> would be obvious what's happening. If they are just in the commit
> messages, it's much harder to notice.

--
Julio M. Merino Vidal <address@hidden>