From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Tim X Newsgroups: gmane.emacs.help Subject: Re: Why maintain old style ChangeLog? Date: Sat, 18 Sep 2010 09:58:47 +1000 Organization: Unlimited download news at news.astraweb.com Message-ID: <87wrqjsz0o.fsf@puma.rapttech.com.au> References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: dough.gmane.org 1291870353 13117 80.91.229.12 (9 Dec 2010 04:52:33 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Thu, 9 Dec 2010 04:52:33 +0000 (UTC) To: help-gnu-emacs@gnu.org Original-X-From: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Thu Dec 09 05:52:28 2010 Return-path: Envelope-to: geh-help-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1PQYUU-0002lG-LB for geh-help-gnu-emacs@m.gmane.org; Thu, 09 Dec 2010 05:52:26 +0100 Original-Received: from localhost ([127.0.0.1]:37457 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1PQYUU-0006ev-1t for geh-help-gnu-emacs@m.gmane.org; Wed, 08 Dec 2010 23:52:26 -0500 Original-Path: usenet.stanford.edu!news.glorb.com!news2.glorb.com!news-xfer.nntp.sonic.net!news.astraweb.com!border2.newsrouter.astraweb.com!not-for-mail Original-Newsgroups: gnu.emacs.help User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.50 (gnu/linux) Cancel-Lock: sha1:m35+r1kfN+k9J5FCadVZCaUfqQw= Original-Lines: 113 Original-NNTP-Posting-Host: 1e666ac7.news.astraweb.com Original-X-Trace: DXC=jNMIB; P8j=GMnc]O[a9m]EL?0kYOcDh@JW\:Hm@YlDbJ1RU8R=ccZjKEjbCDJKa`P@hPVQihHfJIL Original-Xref: usenet.stanford.edu gnu.emacs.help:181363 X-BeenThere: help-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Users list for the GNU Emacs text editor List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Errors-To: help-gnu-emacs-bounces+geh-help-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.help:76684 Archived-At: Oleksandr Gavenko 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 > 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