From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 31385 invoked by alias); 21 Mar 2006 16:42:12 -0000 Received: (qmail 31374 invoked by uid 22791); 21 Mar 2006 16:42:10 -0000 X-Spam-Check-By: sourceware.org Received: from nevyn.them.org (HELO nevyn.them.org) (66.93.172.17) by sourceware.org (qpsmtpd/0.31.1) with ESMTP; Tue, 21 Mar 2006 16:41:16 +0000 Received: from drow by nevyn.them.org with local (Exim 4.54) id 1FLjur-0007cR-5y; Tue, 21 Mar 2006 11:41:05 -0500 Date: Tue, 21 Mar 2006 19:55:00 -0000 From: Daniel Jacobowitz To: "Brian J. Fox" Cc: Denis PILAT , Chet Ramey , Eli Zaretskii , gdb-patches@sources.redhat.com, bash-maintainers@gnu.org Subject: Re: [patch-readline] history file reading Message-ID: <20060321164105.GA29111@nevyn.them.org> Mail-Followup-To: "Brian J. Fox" , Denis PILAT , Chet Ramey , Eli Zaretskii , gdb-patches@sources.redhat.com, bash-maintainers@gnu.org References: <20060321145842.GA25689@nevyn.them.org> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.8i X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-03/txt/msg00247.txt.bz2 On Tue, Mar 21, 2006 at 08:29:20AM -0800, Brian J. Fox wrote: > > From: Daniel Jacobowitz > > Date: Tue, 21 Mar 2006 09:58:42 -0500 > > To: Denis PILAT , Chet Ramey > > Cc: Eli Zaretskii , , > > > > Subject: Re: [patch-readline] history file reading > > > > Our ChangeLog entries have two spaces between date and name, and two > > between name and date. The indented portion starts with a tab on every > > line. The first character should usually be capitalized. Also, they > > cover only "what" and not "why". > > Since when do ChangeLog entries not say "why"? Without this information, it > is impossible to tell if the change needs to stay or not in the future. > > I've certainly always included "why" in my ChangeLog entries. > > Is this a personal preference, or are you quoting a new GNU mantra? In the GNU projects I've worked in, this is the usual interpretation of the existing GNU coding standards: http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html#Change-Log-Concepts There's no need to describe the full purpose of the changes or how they work together. If you think that a change calls for explanation, you're probably right. Please do explain it - but please put the explanation in comments in the code, where people will see it whenever they see the code. For example, New function is enough for the change log when you add a function, because there should be a comment before the function definition to explain what it does. And from GCC: 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. -- Daniel Jacobowitz CodeSourcery