Re: just checked in

[Roland McGrath <roland@frob.com>]

I've CC'd this to libc-hacker because I want everyone to be aware of the
importance of writing down the important details in ChangeLog entries
and/or in comments in the code.


> Roland McGrath <roland@frob.com> writes:
> 
> > Your change logs are sloppy.
> 
> I know.  I hardly have the time to make the changes.

It only takes a minute to make decent change log entries.  It barely takes
any effort at all if you make them incrementally while you are changing the
code.  It will save untold hours, days, and weeks of work in the future for
ourselves and other hackers.  If the code progresses a bit slower, but
stays more understandable and the history preserved so the code can be
maintained for a long time in the future, in the long run that helps
everyone a lot more than having three more little hacks this weekend rather
than next.  Please, please, please, remember that the source and its
usability by everyone for the long term is what matters.  If it becomes an
unmaintainable mess, it barely matters anymore that it's free.

> > dlfcn.h has user-visible changes that have nothing whatsoever to do with
> > the large set of ld.so changes, but you just stuck "Likewise" in the log
> > entry as if that explained it.
> 
> I forgot about this.  It's changed now.

Thanks.

> I use ChangeLogs (normally) the way they are intended to be, for user
> visible changes.  But describing such a massive and for the
> user-invisible change is only useful for other developers.  I
> explained the changes in the notification I sent out.

You are completely and dangerously confused or misinformed about the
purpose of ChangeLogs.  They DO NOT exist for users to read; they exist for
other developers to read, and for hackers to read when they get the source
years from now.  It is NOT good enough that you sent a mail message (even
if it had been to a public mailing list).  The source must all be in the
source distribution, and any commentary that goes with it belongs there too
(and for any large source base, the history and historical rationales are
essential commentary).  This priority is central to the entire philosophy
of GNU.  If every person on libc-hacker dies today, the development of GNU
libc must go on, and the cvs repository is the only thing we can be sure
those who take it up next will have to refer to.

Take the time to write the log entries instead, and put the log entries in
the mail message.  We will all thank you for it now and in years to come.
Please trust my experience on this.  There are many log entries I've made
in the past much more detailed than yours, that I have since cursed myself
for making so vague that coming back months or years later I could no
longer reconstruct the rationale--hours and days of time wasted because I
didn't take another few seconds to give details in the log entry that would
have made simple searching and reading in the ChangeLog tell me what I
needed right away.  (And this even though I have my own archives of mail
I've sent for years back to search in.)

The place to record user-visible changes for users to read about is NEWS;
that's exactly what NEWS is for.  It is not so vital that NEWS be updated
accurately right when you make the changes; good ChangeLog discipline means
that you (or anyone else familiar with the code) can simply scan the log
entries since the last release to cull the user-visible changes to go in
NEWS when preparing to make a new public release for users (hackers using
test releases can be expected to read ChangeLog).