Re: Why maintain old style ChangeLog?

[Tim X]

Oleksandr Gavenko <gavenkoa@gmail.com> writes:

> I also ask similar question at (and not completely
> satisfied by answers):
>
> http://stackoverflow.com/questions/3712969/why-maintain-traditional-detailed-changelog-in-modern-world-with-svn-mercurial
>
>
> I read "Sending Patches for GNU Emacs" section of 'info emacs'.
>
> It contains requirement for writing ChangeLog entry
> to describe your changes.
>
> I check emacs/trunk/man/trouble.texi (at oldest available in bzr??)
> revision:
>
> revno: 25830
> committer: Dave Love <xxx@gnu.org>
> timestamp: Wed 1999-09-29 15:17:24 +0000
>
> From this revision:
>
> ================================================================
> The purpose of the change log is to show people where to find what was
> changed.  So you need to be specific about what functions you changed;
> in large functions, it's often helpful to indicate where within the
> function the change was.
>
> On the other hand, once you have shown people where to find the change,
> you need not explain its purpose in the change log.  Thus, if you add a
> new function, all you need to say about it is that it is new.  If you
> feel that the purpose needs explaining, it probably does---but put the
> explanation in comments in the code.  It will be more useful there.
> ================================================================
>
> "where to find what was changed" you can easy done by 'bzr log'.
>
> Or ever more precisely with "bzr log --show-diff".
>
> I think that this statement archaic and search changes
> from 13.6 MiB spit Emacs ChangeLogs not so convenient
> as 'bzr log' on source root (and don't forget ability
> restrict search with date by '-r date1:date2' or dir or fileset).
>
>
>
> Second paragraph state that you need describe WHAT
> and not write WHY.
>
> For me this is not always right.
>
> You can write source in literate programming style,
> so we get a lot of doc and a few of code.
>
> Write comment in code that next line fix behavior on
> "another dumb OS with gcc 2.x.x and system ld" ugly.
>
> Much pretty hold this remark as metadata in VCS.
>
> 'bzr annotate' gives revision for line
> and next you can get log message, full diff.
>
> With Emacs VC you can easy jump deep in history to get
> searched log message (vc-annotate-revision-previous-to-line).
>
> I think that commit history is a part of source code.
> And must be GPLed. And GPL must require availability
> history of changes not only sources! This make program more
> easy support and so more free.
>
>
>
>
> But back to the original question.
>
> Does need prepare ChangeLog entry for patch at current time?
>
> And does need maintain ChangeLog at all in view
> of modern VCS tools?

I agree that the facilities of the version control system do provide you
with lots of additional functionality, much of which does duplicate what
was previously provided via ChangeLog. However, I don't think it is an
either/or situation.

Many people don't run a full version control branch. Instead they just
download a snapshot or tar ball. These people don't ahve the version
control history and meta data. For them, the change log is important.
Likewise, many VC systems support the concept of a light weight branch,
which sacrifices some of the meta data to reduce download/update time or
storage requirements. For these users the ChangeLog is also important. 

Sometimes, I find it faster and more convenient to just glance at the
changelog rather than use something like bzr log. 

If I understand your point regarding putting comments as meta data in VC
rather than as comments in source code, I disagree totally. Although
putting the comments in the code may seem 'ugly', I'd rather have them
there than just in VC meta data. When I'm looking at code, I don't want
to have to remember to check the version control system to get
additional details/comments etc. I want to be able to look at a
screenful of code and comments and have an idea why things have been
done the way they have. 

I don't think it is an either/or situation. Both facilities have
benefits and I don't think it is too much of a maintenance overhead to
maintain the change logs. Different strokes for different folks. 

Tim


-- 
tcross (at) rapttech dot com dot au