Index: standards.texi =================================================================== RCS file: /sources/gnustandards/gnustandards/standards.texi,v retrieving revision 1.249 diff -u -r1.249 standards.texi --- standards.texi 25 Jul 2016 17:05:18 -0000 1.249 +++ standards.texi 3 Aug 2017 18:39:20 -0000 @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: address@hidden lastupdate July 25, 2016 address@hidden lastupdate August 3, 2017 @c %**end of header @dircategory GNU organization @@ -3526,14 +3526,32 @@ @section Change Logs @cindex change logs -Keep a change log to describe all the changes made to program source +Describe all changes made to program source files, either by +maintaining a change description in a public version control system, +or by keeping a change log that is distributed along with the 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 +More importantly, change descriptions can help you eliminate conceptual inconsistencies between different parts of a program, by giving you a history of how the conflicting concepts arose and who they came from. +Change descriptions are commonly recorded via a version control system +such as Git. If developers use a publicly-accessible distributed +version control system, and if commits track change authors and have +commit messages that contain useful information at the human level for +understanding the change, then the combination of the commits' +authorship, messages, and source-code changes should suffice to +describe the changes. In this case, maintainers of a program should +establish a good format for its commit messages; a popular choice is +the @file{ChangeLog} format described below, except without the +initial tab indentation, and with authorship and time stamp recorded +automatically by the version control system. + +In the unlikely event that you do not use a version control system, +maintain and distribute a change log as a text file in address@hidden format. + @menu * Change Log Concepts:: * Style of Change Logs:: @@ -3566,15 +3584,22 @@ However, we've been advised that it is a good idea to include them, for the sake of copyright records. -The change log file is normally called @file{ChangeLog} and covers an +When change logs are maintained in a text file, +the change log file is normally called @file{ChangeLog} and covers an entire directory. Each directory can have its own change log, or a directory can use the change log of its parent directory---it's up to you. -Another alternative is to record change log information with a version -control system such as RCS or CVS. This can be converted automatically -to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command address@hidden v a} (@code{vc-update-change-log}) does the job. +Some projects record change log information with a version control +system such as Git, and automatically generate change log files from +the version-control record. For example, when developing Emacs, the +shell command @samp{make change-history} generates a @file{ChangeLog} +file from the Git history. With this approach, the resulting address@hidden files can be further edited by hand, to fix errors in +the change log record. However, altering the metahistory in this way +can be confusing and is a maintenance burden, and it is generally more +efficient overall to keep the metahistory in the version control +system. For changes to code, there's no need to describe the full purpose of the changes or how they work together. If you think that a change @@ -3586,10 +3611,15 @@ explain what it does, how to call it, and so on. For changes to files that do not support a comment syntax (e.g., media -files), it is ok to include the full explanation in the change log file, +files), it is ok to include the full explanation in the change description, after the title and before the list of individual changes. -The easiest way to add an entry to @file{ChangeLog} is with the Emacs +When using a version control system, an easy way to add a change +description is with the Emacs command @kbd{C-x v v}, which runs +the command @samp{vc-next-action}. + +When not using a version control system, an easy way to add an entry +to @file{ChangeLog} is with the Emacs command @kbd{M-x add-change-log-entry}. An individual change should have an asterisk, the name of the changed file, and then in parentheses the name of the changed functions, variables or whatever, @@ -3604,24 +3634,25 @@ 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 and GCC.) +drawn from Emacs.) address@hidden -1998-08-17 Richard Stallman address@hidden +2015-08-12 Eli Zaretskii -* register.el (insert-register): Return nil. -(jump-to-register): Likewise. + Fix display of thin lines whose newline has line-height property of t + * src/xdisp.c (append_space_for_newline): Don't try to fix ascent + and descent values of non-empty glyph rows, since they could have + forced low values deliberately. (Bug#21243) -* sort.el (sort-subr): Return nil. +2015-08-12 Richard Stallman -* 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. + Offer to combine multiple To or CC fields. + * lisp/mail/sendmail.el (mail-combine-fields): New function. + (mail-send): Call 'mail-combine-fields'. -* 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. address@hidden example + Don't decrypt encrypted files. + * lisp/mail/mail-utils.el (mail-file-babyl-p): Bind epa-inhibit to t. address@hidden smallexample It's important to name the changed function or variable in full. Don't abbreviate function or variable names, and don't combine them.