Re: Org merge

["Stephen J. Turnbull" <stephen@xemacs.org>]

Bastien writes:

 > > The usual course of action for new functions is to describe them in
 > > ChangeLog as:
 > >
 > >     (foo, bar, baz): New function.
 > >
 > > so other than enumerating them, there's nothing to do.
 > 
 > Yes -- my point was that some functions that are currently listed as
 > "new functions" in the Changelog I posted are part of the clean room
 > implementation, others are new functions corresponding to new
 > features.  I will clean up the Changelog to only document the
 > latter.

No, the point of the ChangeLog entry is to make it straightforward to
find out what identifiers (functions and variables) are new (for
review at the time of integration), and when they were introduced (for
context in debugging and study later).

You should list all new global identifiers (functions and variables).
It's not necessary (although some projects prefer to do so) to
document the functionality added in the ChangeLog -- the docstring or
comment in the code does that for developers, and NEWS does it in
cases where the new identifier is something that users use.

N.B. Making such a list is something that can't be done (at least not
trivially) with the VCS itself; the developer has to do it mostly by hand.

Steve