ChangeLog entries should be full sentences, not sentence fragments. Fragments are more often ambiguous, and it takes only a few more seconds to write out what you mean. Fragments like `New file' or `New function' are acceptable, because they are standard idioms, and all further details should appear in the source code.
The log entry should mention every file changed. It should also mention by name every function, variable, macro, makefile target, grammar rule, etc. you changed. However, there are common-sense exceptions:
In general, there is a tension between making entries easy to find by searching for identifiers, and wasting time or producing unreadable entries by being exhaustive. Use your best judgement -- and be considerate of your fellow developers.
Group ChangeLog entries into "paragraphs", separated by blank lines. Each paragraph should be a set of changes that accomplish a single goal. Independent changes should be in separate paragraphs. For example:
1999-03-24 Stan Shebs address@removed * configure.host (mips-dec-mach3*): Use mipsm3, not mach3. Attempt to sort out SCO-related configs. * configure.host (i[3456]86-*-sysv4.2*): Use this instead of i[3456]86-*-sysv4.2MP and i[3456]86-*-sysv4.2uw2*. (i[3456]86-*-sysv5*): Recognize this. * configure.tgt (i[3456]86-*-sco3.2v5*, i[3456]86-*-sco3.2v4*): Recognize these.
Even though this entry describes two changes to `configure.host', they're in separate paragraphs, because they're unrelated changes. The second change to `configure.host' is grouped with another change to `configure.tgt', because they both serve the same purpose.
Also note that the author has kindly recorded his overall motivation for the paragraph, so we don't have to glean it from the individual changes.
The header line for the ChangeLog entry should have the format shown above. If you are using an old version of Emacs (before 20.1) that generates entries with more verbose dates, consider using `etc/add-log.el', from the GDB source tree. If you are using vi, consider using the macro in `etc/add-log.vi'. Both of these generate entries in the newer, terser format.
One should never need the ChangeLog to understand the current code. If you find yourself writing a significant explanation in the ChangeLog, you should consider carefully whether your text doesn't actually belong in a comment, alongside the code it explains. Here's an example of doing it right:
1999-02-23 Tom Tromey address@removed
* cplus-dem.c (consume_count): If `count' is unreasonable,
return 0 and don't advance input pointer.
And then, in `consume_count' in `cplus-dem.c':
while (isdigit ((unsigned char)**type))
{
count *= 10;
count += **type - '0';
/* A sanity check. Otherwise a symbol like
`_Utf390_1__1_9223372036854775807__9223372036854775'
can cause this function to return a negative value.
In this case we just consume until the end of the string. */
if (count > strlen (*type))
{
*type = save;
return 0;
}
This is why a new function, for example, needs only a log entry saying "New Function" -- all the details should be in the source.
Avoid the temptation to abbreviate filenames or function names, as in this example (mostly real, but slightly exaggerated):
* gdbarch.[ch] (gdbarch_tdep, gdbarch_bfd_arch_info,
gdbarch_byte_order, {set,}gdbarch_long_bit,
{set,}gdbarch_long_long_bit, {set,}gdbarch_ptr_bit):
Corresponding functions.
This makes it difficult for others to search the ChangeLog for changes to the file or function they are interested in. For example, if you searched for `set_gdbarch_long_bit', you would not find the above entry, because the writer used CSH-style globbing to abbreviate the list of functions. If you gave up, and made a second pass looking for gdbarch.c, you wouldn't find that either. Consider your poor readers, and write out the names.