[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[patch] Allow full explanation in change log for certain changes
From: |
Thien-Thi Nguyen |
Subject: |
[patch] Allow full explanation in change log for certain changes |
Date: |
Mon, 04 Jun 2012 11:52:37 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.0.92 (gnu/linux) |
Rationale: We currently urge rationale/why information to be placed
in the comments, and that should not change. This change maintains
that spirit, giving guidance for cases when "comments in code" is
impossible.
Notes:
- I discarded the "unwieldly" argument from the rationale since that
kind of optimization is handled later (node "Simple Changes").
Anyway, "impossible" is strong enough to stand by itself.
- Moving "in the past" paragraph back serves two purposes: providing
a foreshadowing (of sorts) for the "no comment syntax" concept;
and giving it more "high level / introductory" feel rather than
the current "oh, BTW" feel (improved flow of concepts). Further
improvement along these lines would be to simply omit "In the past",
and reword to positively enumerate those files that deserve change
log mention. (I like such historic notes, personally, however.)
Here is a suitable ChangeLog entry:
2012-06-04 Thien-Thi Nguyen <address@hidden>
Allow full explanation in change log for certain changes.
* doc/standards.texi (Change Log Concepts): Define "title";
move it into initial paragraph. Move "In the past,
... sake of copyright records" paragraph earlier.
Restrict disdain for full explanation to changes in code.
Add paragraph allowing full explanation for files that
have no comment syntax.
Here is the diff:
doc/standards.texi | 21 ++++++++++++++-------
1 files changed, 14 insertions(+), 7 deletions(-)
diff --git a/doc/standards.texi b/doc/standards.texi
index 60a0ea2..9ddd68c 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3541,6 +3541,14 @@ @node Change Log Concepts
a change log describes either an individual change or the smallest
batch of changes that belong together, also known as a @dfn{change
set}.
address@hidden title, change log entry
+For later reference or for summarizing, sometimes it is useful to start the
+entry with a one-line @dfn{title} to describe its overall purpose.
+
+In the past, we recommended not mentioning changes in non-software
+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 change log file is normally called @file{ChangeLog} and covers an
entire directory. Each directory can have its own change log, or a
@@ -3552,9 +3560,9 @@ @node Change Log Concepts
to a @file{ChangeLog} file using @code{rcs2log}; in Emacs, the command
@kbd{C-x v a} (@code{vc-update-change-log}) does the job.
-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 log entry. If
+For changes to code, there's no need to describe the full purpose of the
+changes or how they work together.
+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
@@ -3562,10 +3570,9 @@ @node Change Log Concepts
function, because there should be a comment before the function
definition to explain what it does.
-In the past, we recommended not mentioning changes in non-software
-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.
+For changes to files that do not support comment syntax (e.g., media
+files), it is OK to include the full explanation in the change log file,
+after the title and before the list of individual changes.
The easiest way to add an entry to @file{ChangeLog} is with the Emacs
command @kbd{M-x add-change-log-entry}. An individual change should
- [patch] Allow full explanation in change log for certain changes,
Thien-Thi Nguyen <=