diff options
author | Karl Berry <karl@freefriends.org> | 2012-07-01 09:30:32 -0700 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-07-01 09:30:32 -0700 |
commit | 2fc09cc631a26404d9332dbd0489a1994be43d13 (patch) | |
tree | bd0818890930b8e0fae855df2a7163ea13905c24 /doc/standards.texi | |
parent | b9edd532da64403e0e017b8028c2f69ff1754126 (diff) | |
download | gnulib-2fc09cc631a26404d9332dbd0489a1994be43d13.tar.gz |
autoupdate
Diffstat (limited to 'doc/standards.texi')
-rw-r--r-- | doc/standards.texi | 38 |
1 files changed, 23 insertions, 15 deletions
diff --git a/doc/standards.texi b/doc/standards.texi index 60a0ea2c8f..fc92652786 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate June 1, 2012 +@set lastupdate June 30, 2012 @c %**end of header @dircategory GNU organization @@ -3541,6 +3541,16 @@ explanation of how the earlier version differed. Each @dfn{entry} in a change log describes either an individual change or the smallest batch of changes that belong together, also known as a @dfn{change set}. +@cindex title, change log entry +@cindex description, change log entry +For later reference or for summarizing, sometimes it is useful to +start the entry with a one-line description (sometimes called a +@dfn{title}) to describe its overall purpose. + +In the past, we recommended not mentioning changes in non-software +files (manuals, help files, media files, etc.)@: in change logs. +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 entire directory. Each directory can have its own change log, or a @@ -3552,20 +3562,18 @@ control system such as RCS or CVS. This can be converted automatically to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command @kbd{C-x v a} (@code{vc-update-change-log}) does the job. -There's no need to describe the full purpose of the changes or how -they work together. However, sometimes it is useful to write one line -to describe the overall purpose of a change log entry. If -you think that a change calls for explanation, you're probably right. -Please do explain it---but please put the full explanation in comments -in the code, where people will see it whenever they see the code. For -example, ``New function'' is enough for the change log when you add a -function, because there should be a comment before the function -definition to explain what it does. - -In the past, we recommended not mentioning changes in non-software -files (manuals, help files, media files, etc.)@: in change logs. -However, we've been advised that it is a good idea to include them, -for the sake of copyright records. +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 +calls for explanation, you're probably right. Please do explain +it---but please put the full explanation in comments in the code, +where people will see it whenever they see the code. For example, +``New function'' is enough for the change log when you add a function, +because there should be a comment before the function definition to +explain what it does. + +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, +after the title and before the list of individual changes. The easiest way to add an entry to @file{ChangeLog} is with the Emacs command @kbd{M-x add-change-log-entry}. An individual change should |