6.8.2 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 it was installed, followed by descriptions of specific changes. (These examples are drawn from Emacs.) Keep in mind that the line which shows the date of the change and the author’s name and email address is needed only in a separate ChangeLog file, not when the change logs are kept in a VCS.

2019-08-29  Noam Postavsky  <[email protected]>

	Handle completely undecoded input in term (Bug#29918)

	* lisp/term.el (term-emulate-terminal): Avoid errors if the whole
	decoded string is eight-bit characters.  Don't attempt to save the
	string for next iteration in that case.
	* test/lisp/term-tests.el (term-decode-partial)
	(term-undecodable-input): New tests.

2019-06-15  Paul Eggert  <[email protected]>

	Port to platforms where tputs is in libtinfow

	* configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).

2019-02-08  Eli Zaretskii  <[email protected]>

	Improve documentation of 'date-to-time' and 'parse-time-string'

	* doc/lispref/os.texi (Time Parsing): Document
	'parse-time-string', and refer to it for the description of
	the argument of 'date-to-time'.

	* lisp/calendar/time-date.el (date-to-time): Refer in the doc
	string to 'parse-time-string' for more information about the
	format of the DATE argument.  (Bug#34303)

If you mention the names of the modified functions or variables, it’s important to name them 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. Don’t put blank lines between individual changes of an entry. You can omit the file name and the asterisk when successive individual changes are in the same file.

Break long lists of function names by closing continued lines with ‘)’, rather than ‘,’, and opening the continuation with ‘(’. This makes highlighting in Emacs work better. Here is an example:

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

The easiest way to add an entry to ChangeLog is with the Emacs command M-x add-change-log-entry, or its variant C-x 4 a (add-change-log-entry-other-window). This automatically collects the name of the changed file and the changed function or variable, and formats a change log entry according to the conventions described above, leaving it up to you to describe the changes you made to that function or variable.

When you install someone else’s changes, put the contributor’s name in the change log entry rather than in the text of the entry. In other words, write this:

2002-07-14  John Doe  <[email protected]>

        * sewing.c: Make it sew.

rather than this:

2002-07-14  Usual Maintainer  <[email protected]>

        * sewing.c: Make it sew.  Patch by [email protected].

When committing someone else’s changes into a VCS, use the VCS features to specify the author. For example, with Git, use git commit --author=author.

As for the date, that should be the date you applied the change. (With a VCS, use the appropriate command-line switches, e.g., git commit --date=date.)

Modern VCS have commands to apply changes sent via email (e.g., Git has git am); in that case the author of the changeset and the date it was made will be automatically gleaned from the email message and recorded in the repository. If the patches are prepared with suitable VCS commands, such as git format-patch, the email message body will also have the original author of the changeset, so resending or forwarding the message will not interfere with attributing the changes to their author. Thus, we recommend that you request your contributors to use commands such as git format-patch to prepare the patches.