[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH] clarify "change log entry"
From: |
Karl Berry |
Subject: |
Re: [PATCH] clarify "change log entry" |
Date: |
Fri, 1 Jun 2012 17:20:30 GMT |
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
- Re: [PATCH] clarify "change log entry",
Karl Berry <=