bug-standards
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[PATCH] clarify "change log entry"


From: Thien-Thi Nguyen
Subject: [PATCH] clarify "change log entry"
Date: Wed, 30 May 2012 11:54:09 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux)

Rationale: Although people can infer "batch of changes" to mean
"change set", the latter is current and it's better to be explicit.
Separating "change log entry" from "individual change" and instead
associating it with "change set" makes it easier to refer to later.

Miscellaneous notes:

- We recycle "batch of changes", moving it earlier, and only
  introduce "change set" as informative instead of normative.  I
  think this better preserves the style, and is also less pushy.
  (It also provides a well-defined place for maintaining currency;
  this epoch's "change set" is last epoch's "delta" is next epoch's
  "unit transform" (or whatever), all of which can be chained onto
  that "aka", should the desire arise...)

- The last hunk (under "@node Conditional Changes") could be
  considered a separate proposal, applicable independently of this
  one in a strict sense (although IMO best applied as a prerequisite
  of this one, as it fixes a bug).  An alternative would be to say
  "here is an entry excerpt" in the paragraph preceding the example
  instead of merely "here is an entry".

Here's the diff:

 doc/standards.texi |   20 ++++++++++++++------
 1 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/doc/standards.texi b/doc/standards.texi
index d2e54a7..2f657f3 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3536,6 +3536,9 @@ @node Change Log Concepts
 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 +3552,7 @@ @node Change Log Concepts

 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
@@ -3563,7 +3566,7 @@ @node Change Log Concepts
 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
+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.
@@ -3605,10 +3608,10 @@ @node Style of Change Logs
 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
@@ -3736,6 +3739,11 @@ @node Conditional Changes
 (gethostname) [!HAVE_SOCKETS]: Replace with winsock version.
 @end example

address@hidden
+Note that this is incomplete; the asterisk and filename are
+presumably on a previous line, along with the first individual
+change to that file.
+
 @node Indicating the Part Changed
 @subsection Indicating the Part Changed

reply via email to

[Prev in Thread] Current Thread [Next in Thread]