gnustandards ChangeLog standards.texi

[Karl Berry]

CVSROOT:        /sources/gnustandards
Module name:    gnustandards
Changes by:     Karl Berry <karl>       12/06/01 17:15:43

Modified files:
        .              : ChangeLog standards.texi 

Log message:
        clarify changelog terminology

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnustandards/ChangeLog?cvsroot=gnustandards&r1=1.163&r2=1.164
http://cvs.savannah.gnu.org/viewcvs/gnustandards/standards.texi?cvsroot=gnustandards&r1=1.216&r2=1.217

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnustandards/gnustandards/ChangeLog,v
retrieving revision 1.163
retrieving revision 1.164
diff -u -b -r1.163 -r1.164
--- ChangeLog   21 May 2012 00:38:10 -0000      1.163
+++ ChangeLog   1 Jun 2012 17:15:42 -0000       1.164
@@ -1,3 +1,20 @@
+2012-06-01  Thien-Thi Nguyen  <address@hidden>
+       and Karl Berry  <address@hidden>
+
+       Clarify ChangeLog terminology.
+       * standards.texi (Change Log Concepts): more clearly distinguish
+       an individual change from the batch of changes typically
+       comprising a change log entry.  Mention the term "change set".
+       (Style of Change Logs): likewise.
+       (Conditional Changes): add filename to last example.
+       bug-standards, 30 May 2012 11:54:09.
+
+2012-05-26  Karl Berry  <address@hidden>
+
+       * standards.texi (Change Log Concepts): media files are
+       another example of non-software files worth mentioning.
+       Suggestion from Thien-Thi Nguyen, 25 May 2012 09:29:31.
+
 2012-05-20  Ward Vandewege  <address@hidden>
 
        * maintain.texi (FTP Upload Directive File - v1.2): new node.

Index: standards.texi
===================================================================
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.216
retrieving revision 1.217
diff -u -b -r1.216 -r1.217
--- standards.texi      8 Apr 2012 00:22:33 -0000       1.216
+++ standards.texi      1 Jun 2012 17:15:42 -0000       1.217
@@ -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 April 7, 2012
address@hidden lastupdate June 1, 2012
 @c %**end of header
 
 @dircategory GNU organization
@@ -3531,11 +3531,16 @@
 @node Change Log Concepts
 @subsection Change Log Concepts
 
address@hidden change set
address@hidden batch of changes
 You can think of the change log as a conceptual ``undo list'' which
 explains 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.
+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 @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}.
 
 The change log file is normally called @file{ChangeLog} and covers an
 entire directory.  Each directory can have its own change log, or a
@@ -3549,7 +3554,7 @@
 
 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 or a batch of changes.  If
+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
@@ -3558,15 +3563,17 @@
 definition to explain what it does.
 
 In the past, we recommended not mentioning changes in non-software
-files (manuals, help 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.
+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 easiest way to add an entry to @file{ChangeLog} is with the Emacs
-command @kbd{M-x add-change-log-entry}.  An entry should have an
-asterisk, the name of the changed file, and then in parentheses the name
-of the changed functions, variables or whatever, followed by a colon.
-Then describe the changes you made to that function or variable.
+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,
+followed by a colon.  Then describe the changes you made to that
+function or variable.
+
 
 @node Style of Change Logs
 @subsection Style of Change Logs
@@ -3605,10 +3612,10 @@
 this is not a good idea, since searching for @code{jump-to-register} or
 @code{insert-register} would not find that entry.
 
-Separate unrelated change log entries with blank lines.  When two
-entries represent parts of the same change, so that they work together,
-then don't put blank lines between them.  Then you can omit the file
-name and the asterisk when successive entries are in the same file.
+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
 @samp{)}, rather than @samp{,}, and opening the continuation with
@@ -3733,9 +3740,10 @@
 a certain macro is @emph{not} defined:
 
 @example
-(gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
+* host.c (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
 @end example
 
+
 @node Indicating the Part Changed
 @subsection Indicating the Part Changed