Date:	Tue, 23 May 2000 12:48:36 -0400
From:	Jeff Garzik <jgarzik@mandrakesoft.com>
To:	Linux Kernel Mailing List <linux-kernel@vger.rutgers.edu>
Subject: RFC: kernel changelogs (semi-long)

When analyzing a kernel code change, it is sometimes not possible to
deduce the true meaning of the change from the diff itself.  When this
happens, analysis of the surrounding code is required, sometimes
accompanied by mailing list searches and such.

Occasionally, we even have bad patches which get applied and then
un-applied, over the course of six months or a year.  From many
perspectives -- long term maintenance, short term change evaluation,
general code understanding -- a small changelog entry for each change
seems advantageous.  I think GNOME, egcs, and other projects using
changelogs have experience which bears this out.

Since the kernel doesn't have a canonical source code repository[1], we
must current on the human (but still brilliant) minds of Linus, Alan,
DaveM, sct, tytso, and others.  Therefore I propose to have kernel
changelogs.

Disadvantages exist too...  Gotta get Linus, Alan, and other big
contributors to agree.  It takes more time, especially for people like
Alan who feed lots of changes to Linus.  And people will inevitably
bicker on changelog entry format.

Three small technical notes:
* I prefer an egcs-style format (sample below), but don't feel strongly
about the issue.
* ChangeLogs are generally not patch-friendly, due to the high
possibility of conflicts.  egcs'ers appear to cut-n-paste ChangeLog
entries as necessary.  If changelog entries are to be kept separate from
patches (which seems reasonable if not necessary), this imposes an
addition burden on Linus for each patch sent to him.
* ChangeLogs for drivers/{char,sound,etc} would be nice, but may be
unreasonable.  Documenting core and arch changes seems more important
than doc'ing driver changes.

Overall I believe the advantages outweight the disadvantages.  I've
always felt that sharing knowledge around has a positive effect, and
IMNSHO the Linux kernel community occasionally suffers a bit due to lack
of documentation on changes.

Comments?

Regards,

	Jeff


[1] if you want to get off on THIS tangent, please change the thread
subject :)




Sat May 20 09:30:55 2000  Richard Kenner  <kenner@vlsi1.ultra.nyu.edu>
 
        * alias.c: Clarify some comments.
        (record_base_value): REGNO is unsigned.
        * rtl.h (record_base_value): Likewise.
 
        * alias.c (aliases_everything_p): Don't special-case QImode
here.
        * c-common.c (c_get_alias_set): Do it here.
        Handle BIT_FIELD_REF by getting alias info for arg.
        Use
POINTER_TYPE_P.                                                                                             



-- 
Jeff Garzik              | Liberty is always dangerous, but
Building 1024            | it is the safest thing we have.
MandrakeSoft, Inc.       |      -- Harry Emerson Fosdick

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.rutgers.edu
Please read the FAQ at http://www.tux.org/lkml/