File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File, Up: Documentation 6.8 Change Logs =============== Keep a change log to describe all the changes made to program source files. The purpose of this is so that people investigating bugs in the future will know about the changes that might have introduced the bug. Often a new bug can be found by looking at what was recently changed. More importantly, change logs can help you eliminate conceptual inconsistencies between different parts of a program, by giving you a history of how the conflicting concepts arose, who they came from, and why were the conflicting changes made. Therefore, change logs should be detailed enough and accurate enough to provide the information commonly required for such "software forensics". Specifically, change logs should make finding answers to the following questions easy: * What changes affected a particular source file? * Was a particular source file renamed or moved, and if so, as part of what change? * What changes affected a given function or macro or definition of a data structure? * Was a function (or a macro or the definition of a data structure) renamed or moved from another file, and if so, as part of which change? * What changes deleted a function (or macro or data structure)? * What was the rationale for a given change, and what were its main ideas? * Is there any additional information regarding the change, and if so, where can it be found? Historically, change logs were maintained on specially formatted files. Nowadays, projects commonly keep their source files under a "version control system" (VCS), such as Subversion, or Git, or Mercurial. If the VCS repository is publicly accessible, and changes are committed to it separately (one commit for each logical changeset) and record the authors of each change, then the information recorded by the VCS can be used to produce the change logs out of VCS logs, and to answer the above questions by using the suitable VCS commands. (However, the VCS log messages still need to provide some supporting information, as described below.) Projects that maintain such VCS repositories can decide not to maintain separate change log files, and instead rely on the VCS to keep the change logs. If you decide not to maintain separate change log files, you should still consider providing them in the release tarballs, for the benefit of users who'd like to review the change logs without accessing the project's VCS repository. Scripts exist that can produce 'ChangeLog' files from the VCS logs; for example, the 'gitlog-to-changelog' script, which is part of Gnulib, can do that for Git repositories. In Emacs, the command 'C-x v a' ('vc-update-change-log') does the job of incrementally updating a 'ChangeLog' file from the VCS logs. If separate change log files _are_ maintained, they are normally called 'ChangeLog', and each such file covers an entire directory. Each directory can have its own change log file, or a directory can use the change log of its parent directory--it's up to you. * Menu: * Change Log Concepts:: * Style of Change Logs:: * Simple Changes:: * Conditional Changes:: * Indicating the Part Changed::  File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs, Up: Change Logs 6.8.1 Change Log Concepts and Conventions ----------------------------------------- You can think of the change log as a conceptual "undo list" which states how earlier versions were different from the current version. People can see the current version; they don't need the change log to tell them what is in it. What they want from a change log is a clear explanation of how the earlier version differed. Each "entry" in a change log describes either an individual change or the smallest batch of changes that belong together, also known as a "change set". It is a good idea to start the change log entry with a "header line": a single line that is a complete sentence which summarizes the change set. If you keep the change log in a VCS, this should be a requirement, as VCS commands that show the change log in abbreviated form, such as 'git log --oneline', treat the header line specially. (In a 'ChangeLog' file, the header line follows a line that says who was the author of the change and when it was installed.) Follow the change log entry's header line with a description of the overall change. This should be as long as needed to give a clear description. Pay special attention to aspects of the change set not easily gleaned from the diffs or from the names of modified files and functions: the overall idea of the change and the need for it, and the relations, if any, between changes made to different files/functions. If the change or its reasons were discussed on some public forum, such as the project's issue tracker or mailing list, it is a good idea to summarize the main points of that discussion in the change's description, and include a pointer to that discussion or the issue ID for those who'd like to read it in full. The best place to explain how parts of the new code work with other code is in comments in the code, not in the change log. If you think that a change calls for explanation of _why_ the change was needed--that is, what problem the old code had such that it required this change--you're probably right. Please put the explanation in comments in the code, where people will see it whenever they see the code. An example of such an explanation is, "This function used to be iterative, but that failed when MUMBLE was a tree." (Though such a simple reason would not need this kind of explanation.) The best place for other kinds of explanation of the change is in the change log entry. In particular, comments usually will not say why some code was deleted or moved to another place--that belongs to the description of the change which did that. Following the free-text description of the change, it is a good idea to give a list of names of the entities or definitions that you changed, according to the files they are in, and what was changed in each one. *Note Style of Change Logs::. If a project uses a modern VCS to keep the change log information, as described in *note Change Logs::, explicitly listing the files and functions that were changed is not strictly necessary, and in some cases (like identical mechanical changes in many places) even tedious. It is up to you to decide whether to allow your project's developers to omit the list of changed files and functions from the log entries, and whether to allow such omissions under some specific conditions. However, while making this decision, please consider the following benefits of providing the list of changed entities with each change: * Generation of useful 'ChangeLog' files from VCS logs becomes more difficult if the change log entries don't list the modified functions/macros, because VCS commands cannot reliably reproduce their names from the commit information alone. For example, when there is a change in the header part of a function definition, the heading of the diff hunk as shown in the VCS log commands will name the wrong function as being modified (usually, the function defined before the one being modified), so using those diffs to glean the names of the modified functions will produce inaccurate results. You will need to use specialized scripts, such as 'gitlog_to_changelog.py', mentioned below, to solve these difficulties, and make sure it supports the source languages used by your project. * While modern VCS commands, such as Git's 'git log -L' and 'git log -G', provide powerful means for finding changes that affected a certain function or macro or data structure (and thus might make 'ChangeLog' files unnecessary if you have the repository available), they can sometimes fail. For example, 'git log -L' doesn't support syntax of some programming languages out of the box. Mentioning the modified functions/macros explicitly allows finding the related changes simply and reliably. * Some VCS commands have difficulties or limitations when tracking changes across file moves or renames. Again, if the entities are mentioned explicitly, those difficulties can be overcome. * Users that review changes using the generated 'ChangeLog' files may not have the repository and the VCS commands available to them. Naming the modified entities alleviates that problem. For these reasons, providing lists of modified files and functions with each change makes the change logs more useful, and we therefore recommend to include them whenever possible and practical. It is also possible to generate the lists naming the modified entities by running a script. One such script is 'gitlog_to_changelog.py' (written in Python 3); it is used by the 'glibc' project. Note that this currently supports fewer programming languages than the manual commands provided by Emacs (*note Style of Change Logs::).  File: standards.info, Node: Style of Change Logs, Next: Simple Changes, Prev: Change Log Concepts, Up: Change Logs 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 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 Port to platforms where tputs is in libtinfow * configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977). 2019-02-08 Eli Zaretskii 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 '(' as in this 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 * sewing.c: Make it sew. rather than this: 2002-07-14 Usual Maintainer * sewing.c: Make it sew. Patch by address@hidden. 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.