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 <[email protected]> and Karl Berry <[email protected]> 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 +@cindex change set +@cindex 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
