ChangeLog format (not really Re: S/390: Fix backtrace support forJava)

[Hans-Peter Nilsson <hp at bitrange dot com>]

On Wed, 2 Apr 2003, Michael Matz wrote:
> On Wed, 2 Apr 2003, Hans-Peter Nilsson wrote:
>
> > > libjava/ ChangeLog:
> > >
> > > 	* configure.in (HAVE_BACKTRACE) [s390*-*-linux*]: Define.
> >
> > A common changelog error: that means something else (see
> > GNU coding standards).  Should be
> >     * configure.in (HAVE_BACKTRACE) <s390*-*-linux*>: Define.

First of all, I agree that for this S/390 change, what format
should be used isn't clear and depends on your mind-mapping of
shell constructs to C.  I see the case statements of a
shell-script as analogue to a C case statement, while Ulrich
Weigand sees it as analogue to an #ifdef-sequence.  Very well.
So let's consider C (and possibly C++) only here.

> I noticed your struggle to "correct" ChangeLog entries using this style,
> to make them use the other style.  As this happened repeatedly I counted
> the number of ChangeLog entries which used the <> style with:
>
> % grep "<[^ at ]*>" ChangeLog* | grep -v "\.h>" | wc -l
> 121
>
> while the [] style is used
> % grep "\[[^ at ]*\]" ChangeLog* | grep -v "\.h\]" | wc -l
> 822
>
> times.  Not all of those entries reflect usage like above,

Try "almost none of them".  Your grep statistics are totally
misleading.

> but visually
> verifying them reveals that most of them fit here.  The use of [] dates
> back until FSFChangeLog.11, 1997.

For FSFChangeLog.11, most [] come from regex/glob abominations
like ({sparc,i[3456]86,powerpcle}-*-solaris2*) and almost none
from incorrect use.  Actual <> and [] use as per coding
standards (or your suggested change) disappear in the noise.

> You also often refered to the GNU coding standards.  Those only mention
> two things:  1) to mention changes conditional to on #define, [] should be
> used, and 2) to indicate the part of a function of a change, <> should be
> used.

It's all that's needed!  What more does it need to say?  A
"part" can be totally different things; what you write in the
ChangeLog entry should just be easily spotted.  When applicable,
a good choice is the paricular case statement.

> "part" of a function is not further defined.  From 1) and 2) above does
> not follow, that for switch cases specifically <> should be used, or that
> [] is not allowed.

Well, the switch case is clearly a *part*, and clearly not a
*conditional change*.  I don't understand your "1) and 2)
above"-interpretation; I don't see a [] vs. <> ambiguity at all.
Can you explain your reading please (for C/C++ code)?  Maybe
others are as dense and would be helped. ;-)

> Furthermore I claim, that using [] for differencing all the cases in
> question is clear for all readers of the ChangeLog.  The important
> property of [] and <> is to visually difference their content from the
> environment, and in that regard both forms are totally equal, therefore
> there are no logical reasons to prefer one over the other.

That's your opinion.  I wouldn't particularly care for one or
the if it hadn't been for it being clearly (well...) written
down to be one way and not the other.  If you agree the two are
visually equivalent, why doing it contrary to the coding
standards?  Besides introducing ambiguity, of course.

> Additionally, standards should standardize common practice, instead of
> imposing artificial restrictions, and from the above numbers it's clear
> what the common practice is.

Totally not clear.  Did you look at the actual grep matches for
example (since you mentioned it) for FSFChangeLog.11?

>  I.e. there must be a reason why people (who
> haven't read the coding standards in the same way you seem to have)
> use [] instead of <>.

I don't think people read the coding standards -- for good
reasons; why bother when existing ChangeLog entries should
follow them?  They just copy what they see in an earlier entry.

> I can only speculate on those reasons, but _I_ personally
> find [] more attractive (and I agree that this is not a logical reason,
> but this doesn't make me prefer it less).

I believe it's just carried on from the first recent misuse.

> Given all the above facts I propose we accept [] for naming switch cases
> (and even other things, as the author sees fit), _even_ if this means not
> following GNU coding standards.

Why not propose to adjust the GNU coding standards instead?
That'd be better, less confusing.

>  As I noticed above I think the standards
> don't have language against this, but even if you disagree with that I
> still propose the same, based on the fact of needing to standardize common
> practice.

The "fact" you seem to refer to I think is just recent copycat
misuse.

> Additionally to all that I think we should not make such a big fuzz about
> this.  It's just your evangelizing which made me write this message ;-)

I have nothing to add.  I agree we shouldn't be making a fuss of
it, instead we should just correct erroneous uses.  Doh!  :-)

brgds, H-P