Re: [PATCH] clarify "change log entry"

[Karl Berry]

    Subject: [PATCH] clarify "change log entry"

Looks good to me.  And again, seems sufficiently noncontentious that I
went ahead and installed it, with the usual minor text tweaks.  Diff
below.  (Please write ChangeLog entries for the future patches, BTW. :)

Seems I failed to commit the previous "media files" insert, and didn't
notice in time to stop CVS from doing its thing.  Anyway.

Thanks,
Karl


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.

--- standards.texi      8 Apr 2012 00:22:33 -0000       1.216
+++ standards.texi      1 Jun 2012 17:15:42 -0000       1.217
@@ -3533,7 +3533,12 @@ history of how the conflicting 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}.
 
@@ -3551,3 +3556,3 @@ There's no need to describe the full pur
 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.
@@ -3560,11 +3565,13 @@ 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.
+
 
@@ -3607,6 +3614,6 @@ this is not a good idea, since searching
 
-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.
 
@@ -3735,5 +3742,6 @@ 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