Re: [patch-readline] history file reading

[Daniel Jacobowitz <drow@false.org>]

On Tue, Mar 21, 2006 at 08:29:20AM -0800, Brian J. Fox wrote:
> > From: Daniel Jacobowitz <drow@false.org>
> > Date: Tue, 21 Mar 2006 09:58:42 -0500
> > To: Denis PILAT <denis.pilat@st.com>, Chet Ramey <chet.ramey@case.edu>
> > Cc: Eli Zaretskii <eliz@gnu.org>, <gdb-patches@sources.redhat.com>,
> > <bash-maintainers@gnu.org>
> > 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