Re: [Monotone-devel] monotone Hacking

[Julio M. Merino Vidal]

On Sep 11, 2007, at 2:18 AM, William Uther wrote:

> On 10/09/2007, at 7:49 PM, Thomas Keller wrote:
>
> > Hi all!
> >
> > I've noticed that the changelog some people use for monotone is not
> > quite "GNU-style". I'm sure you all hacked stuff longer than me,  
> > so you
> > can correct me at any time, but aren't we forced to use some kind of
> > GNU-style syntax to make it easier to create a ChangeLog file  
> > afterwards
> > (for whatever distributions need that)? If not, everybody is - of  
> > course
> > - free to use whatever format they do like.
> >
> > I don't like to start a bikeshed discussion here, I just want to be
> > clear. I think it would also be a good idea to include the rules of
> > whatever consense we find here in HACKING.
>
> I think including the rules in HACKING would be a good idea.
>
> Out of interest, who actually converts log messages directly to  
> change logs?  I would
> have thought that most people who distribute Monotone would find  
> the more abstract
> changes described in the NEWS file more relevant.

Indeed.  Personally I have never found ChangeLogs that useful *if* I  
can resort to the development repository to look for the information  
I need.  And in the case of Monotone it's clear that doing that is  
possible :-)  Browsing through the repository archives is usually  
easier, more descriptive and far more accurate than what a ChangeLog  
can say.

For packagers (at least for me, again ;-) the NEWS files are much  
more useful than ChangeLogs because you can quickly get an idea of  
the most important changes between releases.  The exact changes to  
files is irrelevant, unless you are looking for a specific bug fix  
for example.  (And even in this last case, ChangeLogs are annoying  
because the information may be spread among multiple entries making  
it difficult to grasp what happened except for people very familiar  
with the code.)

I'd vote for ditching ChangeLog-style commit messages in favor of  
more descriptive ones (using the approach of a "subject line" at the  
beginning and a large description in the subsequent paragraphs).   
Why?  First of all, Monotone already records the exact changes to the  
files, and mtn log will tell you which of them were modified, added,  
removed, etc.  There is no need to repeat that in the message.  And  
second, this can prevent committing unrelated changes in a single  
commit.  Using a ChangeLog approach, it is often very tempting to  
write a message as:

* a.cc, b.cc: Did blah, blah, blah.
* z.cc: Fixed an unrelated typo.

This commit would be conceptually incorrect because it's doing two  
things at the same time.  Using ChangeLog-style messages seems to  
encourage this approach.  Using plain text messages will make one  
think twice before doing that, because he'll have to explain *why* he  
is committing that at once.

Cheers,

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