Why maintain old style ChangeLog?

Why maintain old style ChangeLog?

[Oleksandr Gavenko]

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?

-- 
Best regards!

Re: Why maintain old style ChangeLog?

[Deniz Dogan]

2010/9/17 Oleksandr Gavenko <gavenkoa@gmail.com>:
> But back to the original question.
>
> Does need prepare ChangeLog entry for patch at current time?
>

Yep.

> And does need maintain ChangeLog at all in view
> of modern VCS tools?
>

Not really, in my opinion. There was a discussion on emacs-devel about
this not too long ago, but I can't find the thread.

-- 
Deniz Dogan

Re: Why maintain old style ChangeLog?

[Eli Zaretskii]

> From: Oleksandr Gavenko <gavenkoa@gmail.com>
> Date: Fri, 17 Sep 2010 19:32:27 +0300
> 
> 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.

This is not a good place to discuss requirements for how to submit
patches to Emacs.  A much better place is emacs-devel@gnu.org.

You may wish to read past discussions about this issue (in the
archives).

Re: Why maintain old style ChangeLog?

[Lowell Gilbert]

Oleksandr Gavenko <gavenkoa@gmail.com> writes:

> But back to the original question.
>
> Does need prepare ChangeLog entry for patch at current time?

I'm not sure what you mean exactly, but I suspect the answer should be 
"not in most environments, but definitely in some environments."

> And does need maintain ChangeLog at all in view
> of modern VCS tools?

In situations where someone may have access to the source code but not
the VCS, maintaining a changelog can be a very considerate thing to do.

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

RE: Why maintain old style ChangeLog?

[Drew Adams]

> 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.

I'd even go so far as to say that delivering a complete change history is part
of the politeness (and freedom) of delivering a program's source code.
Likewise, documentation.

Sure, we could make users jump through hoops to get this info, but why hinder
them?  We could also deliver only binary executables and make them try to
reverse-engineer some source code based on the machine etc. ;-)

Consideration, cooperation, and civility demand giving users as much info as you
have about your program, from soup (requirements descriptions: what it's
supposed to do), through multiple other courses (design descriptions: how it
works, source code with comments, documentation), to nuts (the working binary).