[cdt-dev] Re: [cdt-core-dev] Making ChangeLog entries

["Alain Magloire" <alain@xxxxxxx>]

> 
> I support this as well. I'd also suggest we have ChangeLogs
> for each of the plugins.
> 
> +1
> 

Ok.

It was started .. but ...

1)  The ChangeLog "style" is not uniform, see below on the "right"
    way to do things and URL to GNU coding style for ChangeLog.
    Although, I strongly disagree to put emails in.

2)  For Java, this can be a real pain for example modifying a few files:

2002-10-xx john Doe
	* src/org/eclipse/cdt/internal/text/eclipse2/CRuleBaseDamagerRepairer.java:
	* src/org/eclipse/cdt/internal/ui/wizards/dialogfields/StringButtonDialogField.java:
	Took me more time to get the ChangeLog entry paths right then to fix the code!!

pffff!

   Can we cut this down to a little more human to manage.

	* src/.../internal/ui/wizards/dialogfields/StringButtonDialogField.java:

It would be nice to at least cut the redundant "org/eclipse/cdt" in the path.

======================
 from ftp://ftp.gnu.org/gnu/standards.{info,texi,dvi}
 or to any mirror near you.
==================From Standards.info=============================
Style of Change Logs
--------------------

Here are some simple examples of change log entries, starting with the
header line that says who made the change and when, followed by
descriptions of specific changes.  (These examples are drawn from Emacs
and GCC.)

     1998-08-17  Richard Stallman  <rms@xxxxxxx>
     
     * register.el (insert-register): Return nil.
     (jump-to-register): Likewise.
     
     * sort.el (sort-subr): Return nil.
     
     * tex-mode.el (tex-bibtex-file, tex-file, tex-region):
     Restart the tex shell if process is gone or stopped.
     (tex-shell-running): New function.
     
     * expr.c (store_one_arg): Round size up for move_block_to_reg.
     (expand_call): Round up when emitting USE insns.
     * stmt.c (assign_parms): Round size up for move_block_from_reg.

It's important to name the changed function or variable in full.  Don't
abbreviate function or variable names, and don't combine them.
Subsequent maintainers will often search for a function name to find all
the change log entries that pertain to it; if you abbreviate the name,
they won't find it when they search.

For example, some people are tempted to abbreviate groups of function
names by writing `* register.el ({insert,jump-to}-register)'; this is
not a good idea, since searching for `jump-to-register' or
`insert-register' would not find that entry.
Separate unrelated change log entries with blank lines.  When two
entries represent parts of the same change, so that they work together,
then don't put blank lines between them.  Then you can omit the file
name and the asterisk when successive entries are in the same file.

Break long lists of function names by closing continued lines with `)',
rather than `,', and opening the continuation with `(' as in this
example:

     * keyboard.c (menu_bar_items, tool_bar_items)
     (Fexecute_extended_command): Deal with `keymap' property.