This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
Re: [patch-readline] history file reading
- From: Daniel Jacobowitz <drow at false dot org>
- To: "Brian J. Fox" <bfox at ai dot mit dot edu>
- Cc: Denis PILAT <denis dot pilat at st dot com>, Chet Ramey <chet dot ramey at case dot edu>, Eli Zaretskii <eliz at gnu dot org>, gdb-patches at sources dot redhat dot com, bash-maintainers at gnu dot org
- Date: Tue, 21 Mar 2006 11:41:05 -0500
- Subject: Re: [patch-readline] history file reading
- References: <20060321145842.GA25689@nevyn.them.org> <C04569E0.30716%bfox@ai.mit.edu>
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