* Re: Why maintain old style ChangeLog?
[not found] <mailman.0.1284741168.28175.help-gnu-emacs@gnu.org>
@ 2010-09-17 19:00 ` Lowell Gilbert
2010-09-17 23:58 ` Tim X
1 sibling, 0 replies; 6+ messages in thread
From: Lowell Gilbert @ 2010-09-17 19:00 UTC (permalink / raw)
To: help-gnu-emacs
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.
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: Why maintain old style ChangeLog?
[not found] <mailman.0.1284741168.28175.help-gnu-emacs@gnu.org>
2010-09-17 19:00 ` Why maintain old style ChangeLog? Lowell Gilbert
@ 2010-09-17 23:58 ` Tim X
2010-12-09 17:24 ` Drew Adams
1 sibling, 1 reply; 6+ messages in thread
From: Tim X @ 2010-09-17 23:58 UTC (permalink / raw)
To: help-gnu-emacs
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
^ permalink raw reply [flat|nested] 6+ messages in thread* RE: Why maintain old style ChangeLog?
2010-09-17 23:58 ` Tim X
@ 2010-12-09 17:24 ` Drew Adams
0 siblings, 0 replies; 6+ messages in thread
From: Drew Adams @ 2010-12-09 17:24 UTC (permalink / raw)
To: 'Tim X', help-gnu-emacs
> 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).
^ permalink raw reply [flat|nested] 6+ messages in thread
* Why maintain old style ChangeLog?
@ 2010-09-17 16:32 Oleksandr Gavenko
2010-09-17 16:42 ` Deniz Dogan
2010-09-17 17:00 ` Eli Zaretskii
0 siblings, 2 replies; 6+ messages in thread
From: Oleksandr Gavenko @ 2010-09-17 16:32 UTC (permalink / raw)
To: help-gnu-emacs
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!
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2010-12-09 17:24 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <mailman.0.1284741168.28175.help-gnu-emacs@gnu.org>
2010-09-17 19:00 ` Why maintain old style ChangeLog? Lowell Gilbert
2010-09-17 23:58 ` Tim X
2010-12-09 17:24 ` Drew Adams
2010-09-17 16:32 Oleksandr Gavenko
2010-09-17 16:42 ` Deniz Dogan
2010-09-17 17:00 ` Eli Zaretskii
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).