From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 10943 invoked by alias); 3 Dec 2007 02:41:35 -0000 Received: (qmail 10923 invoked by uid 22791); 3 Dec 2007 02:41:34 -0000 X-Spam-Check-By: sourceware.org Received: from elasmtp-scoter.atl.sa.earthlink.net (HELO elasmtp-scoter.atl.sa.earthlink.net) (209.86.89.67) by sourceware.org (qpsmtpd/0.31) with ESMTP; Mon, 03 Dec 2007 02:41:26 +0000 Received: from [67.38.22.223] (helo=owl.gateway.2wire.net) by elasmtp-scoter.atl.sa.earthlink.net with asmtp (TLSv1:AES256-SHA:256) (Exim 4.34) id 1Iz1FL-0003Tm-Pk for gcc@gcc.gnu.org; Sun, 02 Dec 2007 21:41:24 -0500 Received: from kiesling by owl.gateway.2wire.net with local (Exim 4.63) (envelope-from ) id 1Iz1FF-00027Z-Ky for gcc@gcc.gnu.org; Sun, 02 Dec 2007 21:41:17 -0500 Subject: Re: Rant about ChangeLog entries and commit messages In-Reply-To: <1196628738.6106.16.camel@tim-gcc> To: gcc@gcc.gnu.org Date: Mon, 03 Dec 2007 02:41:00 -0000 X-Mailer: ELM [version 2.4ME+ PL124 (25)] MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Type: text/plain; charset="US-ASCII" Message-Id: From: Robert Kiesling X-ELNK-Trace: 0b901cbc512a9d8594f5150ab1c16ac01a238acc8405a5b0501eb9465b39b48f1825f4cb49f7f9ea350badd9bab72f9c350badd9bab72f9c350badd9bab72f9c Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2007-12/txt/msg00052.txt.bz2 > On Sun, 2007-12-02 at 09:26 -0500, Robert Kiesling wrote: > > > I guess nobody really loves writing ChangeLog entries, but in my opinion there > > > are quite effective "executive summaries" for the patches and helpful to the > > > reader/reviewer. Please let's not throw the baby with the bath's water. > > > > If there's a mechanism to filter checkin messages to ChangeLog summaries, > > I would be happy to use it - in cases of multiple packages, especially, it's > > important to know what changes were made, when, and when the changes propagated > > through packages and releases, and where they got to, occasionally. Anybody > > know of a useful, built-in mechanism for this task? > > > > Personally I find it slow and inefficient tracing through why a given > change was made. It is just a slow process searching and sometimes I > don't bother because it is so inconvenient. The ChangeLog entries > provide little help and there does not seem to be a good alternative. If > there is a good alternative no-one has said what it is so far. > > As people have pointed out, the RCSs pretty well cover the "what" these > days. And writing changelog entries, which largely duplicate this > information, is time-consuming and tedious. And there are of of little > to no value to me at least. > > The coding standards do allow, in some cases, that giving some context > would be useful: > > > See also what the GNU Coding Standards have to say about what goes in > > ChangeLogs; in particular, descriptions of the purpose of code and > > changes should go in comments rather than the ChangeLog, though a > > single line overall description of the changes may be useful above the > > ChangeLog entry for a large batch of changes. > > I personally would strongly favour each ChangeLog entry having a single > line of context. This could be the PR number or a single line giving the > purpose of the change or what bigger change it is part of. > > As pointed out by Zach Weinberg in his paper "A Maintenance Programmer's > View of GCC", there are many impediments to contributing to GCC. > > http://www.linux.org.uk/~ajh/gcc/gccsummit-2003-proceedings.pdf > > Things are not much better than they were when Zach wrote his paper. This small change would be one positive step n the right direction, IMHO. One line of reference would be sufficient provided that branches other than the main development trunk stick to revisions in that branch only. I haven't glanced through the references yet, but maintenance programming is considerably different than writing new code, or even modifying someone else's code. If it's the latter you're trying to achieve, or anticipate achieving, then an accurate line of reference would be most helpful. Unfortunately, then, _someone_ has to maintain the comments accurately. I wouldn't care to say who (whom?)... just... someone. :) -- Ctalk Home Page: http://ctalk-lang.sourceforge.net