It's hard to review a unified diff that you cannot even apply as a patch
(due to the mail forward encapsulation).
For easier review, therefore, find attached:
1) A patch that fixes Texinfo syntax errors,
2) The old and the new modified nodes, as formatted by makeinfo.
To view the changes in a colour-capable terminal, use
$ dwdiff -c standards-changes.old.txt standards-changes.new.txt | less -R
To view them in a terminal without colors, use
$ wdiff -t standards-changes.old.txt standards-changes.new.txt | less -R
--- standards.texi.eli 2020-05-16 19:54:59.186121364 +0200
+++ standards.texi 2020-05-16 19:57:32.134879989 +0200
@@ -3638,7 +3638,7 @@
history of how the conflicting concepts arose, who they came from, and
why were the conflicting changes made.
-@cinex software forensics, and change logs
+@cindex software forensics, and change logs
Therefore, change logs should be detailed enough and accurate enough
to provide the information commonly required for such @dfn{software
forensics}. Specifically, change logs should make finding answers to
@@ -3844,7 +3844,7 @@
@acronym{VCS}.
@example
-2019-08-29 Noam Postavsky <[email protected]>
+2019-08-29 Noam Postavsky <npostavs@@gmail.com>
Handle completely undecoded input in term (Bug#29918)
@@ -3854,13 +3854,13 @@
* test/lisp/term-tests.el (term-decode-partial)
(term-undecodable-input): New tests.
-2019-06-15 Paul Eggert <[email protected]>
+2019-06-15 Paul Eggert <eggert@@cs.ucla.edu>
Port to platforms where tputs is in libtinfow
* configure.ac (tputs_library): Also try tinfow, ncursesw (Bug#33977).
-2019-02-08 Eli Zaretskii <[email protected]>
+2019-02-08 Eli Zaretskii <eliz@@gnu.org>
Improve documentation of 'date-to-time' and 'parse-time-string'
@@ -3955,7 +3955,7 @@
own header line:
@example
-2019-08-29 Eli Zaretskii <[email protected]>
+2019-08-29 Eli Zaretskii <eliz@@gnu.org>
* lisp/simple.el (kill-do-not-save-duplicates): Doc fix. (Bug#36827)
@end example
@@ -3980,7 +3980,7 @@
files in the repository:
@example
-2019-01-07 Paul Eggert <[email protected]>
+2019-01-07 Paul Eggert <eggert@@cs.ucla.edu>
Update copyright year to 2019
File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File,
Up: Documentation
6.8 Change Logs
===============
Keep a change log to describe all the changes made to program source
files. The purpose of this is so that people investigating bugs in the
future will know about the changes that might have introduced the bug.
Often a new bug can be found by looking at what was recently changed.
More importantly, change logs can help you eliminate conceptual
inconsistencies between different parts of a program, by giving you a
history of how the conflicting concepts arose and who they came from.
* Menu:
* Change Log Concepts::
* Style of Change Logs::
* Simple Changes::
* Conditional Changes::
* Indicating the Part Changed::
File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs,
Up: Change Logs
6.8.1 Change Log Concepts
-------------------------
You can think of the change log as a conceptual "undo list" which states
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. Each "entry" in a change log
describes either an individual change or the smallest batch of changes
that belong together, also known as a "change set".
It is a good idea to start the change log entry with a description of
the overall change. This should be as long as needed to give a clear
description.
Then give a list of names of the entities or definitions that you
changed, according to the files they are in, and what was changed in
each one. *Note Style of Change Logs::.
The change log file is normally called 'ChangeLog' and covers an
entire directory. Each directory can have its own change log, or a
directory can use the change log of its parent directory--it's up to
you.
Instead of using a file named 'ChangeLog', you can record the change
log information as log entries in a version control system such as RCS
or CVS. This can be converted automatically to a 'ChangeLog' file using
'rcs2log'; in Emacs, the command 'C-x v a' ('vc-update-change-log') does
the job.
The best place to explain how parts of the new code work with other
code is in comments in the code, not in the change log.
If you think that a change calls for explanation of _why_ the change
was needed--that is, what problem the old code had such that it required
this change--you're probably right. Please put the explanation in
comments in the code, where people will see it whenever they see the
code. An example of such an explanation is, "This function used to be
iterative, but that failed when MUMBLE was a tree." (Though such a
simple reason would not need this kind of explanation.)
The best place for other kinds of explanation of the change is in the
change log entry.
The easiest way to add an entry to 'ChangeLog' is with the Emacs
command '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.
File: standards.info, Node: Style of Change Logs, Next: Simple Changes,
Prev: Change Log Concepts, Up: Change Logs
6.8.2 Style of Change Logs
--------------------------
Here are some simple examples of change log entries, starting with the
header line that says who made the change and when it was installed,
followed by descriptions of specific changes. (These examples are drawn
from Emacs and GCC.)
1998-08-17 Richard Stallman <[email protected]>
* register.el (insert-register): Return nil.
(jump-to-register): Likewise.
* sort.el (sort-subr): Return nil.
* tex-mode.el (tex-bibtex-file, tex-file, tex-region):
Restart the tex shell if process is gone or stopped.
(tex-shell-running): New function.
* expr.c (store_one_arg): Round size up for move_block_to_reg.
(expand_call): Round up when emitting USE insns.
* stmt.c (assign_parms): Round size up for move_block_from_reg.
It's important to name the changed function or variable in full.
Don't abbreviate function or variable names, and don't combine them.
Subsequent maintainers will often search for a function name to find all
the change log entries that pertain to it; if you abbreviate the name,
they won't find it when they search.
For example, some people are tempted to abbreviate groups of function
names by writing '* register.el ({insert,jump-to}-register)'; this is
not a good idea, since searching for 'jump-to-register' or
'insert-register' would not find that entry.
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
')', rather than ',', and opening the continuation with '(' as in this
example:
* keyboard.c (menu_bar_items, tool_bar_items)
(Fexecute_extended_command): Deal with 'keymap' property.
When you install someone else's changes, put the contributor's name
in the change log entry rather than in the text of the entry. In other
words, write this:
2002-07-14 John Doe <[email protected]>
* sewing.c: Make it sew.
rather than this:
2002-07-14 Usual Maintainer <[email protected]>
* sewing.c: Make it sew. Patch by [email protected].
As for the date, that should be the date you applied the change.
File: standards.info, Node: Change Logs, Next: Man Pages, Prev: NEWS File,
Up: Documentation
6.8 Change Logs
===============
Keep a change log to describe all the changes made to program source
files. The purpose of this is so that people investigating bugs in the
future will know about the changes that might have introduced the bug.
Often a new bug can be found by looking at what was recently changed.
More importantly, change logs can help you eliminate conceptual
inconsistencies between different parts of a program, by giving you a
history of how the conflicting concepts arose, who they came from, and
why were the conflicting changes made.
Therefore, change logs should be detailed enough and accurate enough
to provide the information commonly required for such "software
forensics". Specifically, change logs should make finding answers to
the following questions easy:
* What changes affected a particular source file?
* Was a particular source file renamed or moved, and if so, as part
of what change?
* What changes affected a given function or macro or definition of a
data structure?
* Was a function (or a macro or the definition of a data structure)
renamed or moved from another file, and if so, as part of which
change?
* What changes deleted a function (or macro or data structure)?
* What was the rationale for a given change, and what were its main
ideas?
* Is there any additional information regarding the change, and if
so, where can it be found?
Historically, change logs were maintained on specially formatted
files. Nowadays, projects commonly keep their source files under a
"version control system" (VCS), such as Subversion, or Git, or
Mercurial. If the VCS repository is publicly accessible, and changes
are committed to it separately (one commit for each logical changeset)
and record the authors of each change, then the information recorded by
the VCS can be used to produce the change logs out of VCS logs, and to
answer the above questions by using the suitable VCS commands.
(However, the VCS log messages still need to provide some supporting
information, as described below.) Projects that maintain such VCS
repositories can decide not to maintain separate change log files, and
instead rely on the VCS to keep the change logs.
If you decide not to maintain separate change log files, you should
still consider providing them in the release tarballs, for the benefit
of users who'd like to review the change logs without accessing the
project's VCS repository. Scripts exist that can produce 'ChangeLog'
files from the VCS logs; for example, the 'gitlog-to-changelog' script,
which is part of Gnulib, can do that for Git repositories. In Emacs,
the command 'C-x v a' ('vc-update-change-log') does the job of
incrementally updating a 'ChangeLog' file from the VCS logs.
If separate change log files _are_ maintained, they are normally
called 'ChangeLog', and each such file covers an entire directory. Each
directory can have its own change log file, or a directory can use the
change log of its parent directory--it's up to you.
* Menu:
* Change Log Concepts::
* Style of Change Logs::
* Simple Changes::
* Conditional Changes::
* Indicating the Part Changed::
File: standards.info, Node: Change Log Concepts, Next: Style of Change Logs,
Up: Change Logs
6.8.1 Change Log Concepts and Conventions
-----------------------------------------
You can think of the change log as a conceptual "undo list" which states
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. Each "entry" in a change log
describes either an individual change or the smallest batch of changes
that belong together, also known as a "change set".
It is a good idea to start the change log entry with a "header line":
a single line that is a complete sentence which summarizes the change
set. If you keep the change log in a VCS, this should be a requirement,
as VCS commands that show the change log in abbreviated form, such as
'git log --oneline', treat the header line specially. (In a 'ChangeLog'
file, the header line follows a line that says who was the author of the
change and when it was installed.)
Follow the change log entry's header line with a description of the
overall change. This should be as long as needed to give a clear
description. Pay special attention to aspects of the change set not
easily gleaned from the diffs or from the names of modified files and
functions: the overall idea of the change and the need for it, and the
relations, if any, between changes made to different files/functions.
If the change or its reasons were discussed on some public forum, such
as the project's issue tracker or mailing list, it is a good idea to
summarize the main points of that discussion in the change's
description, and include a pointer to that discussion or the issue ID
for those who'd like to read it in full.
The best place to explain how parts of the new code work with other
code is in comments in the code, not in the change log.
If you think that a change calls for explanation of _why_ the change
was needed--that is, what problem the old code had such that it required
this change--you're probably right. Please put the explanation in
comments in the code, where people will see it whenever they see the
code. An example of such an explanation is, "This function used to be
iterative, but that failed when MUMBLE was a tree." (Though such a
simple reason would not need this kind of explanation.)
The best place for other kinds of explanation of the change is in the
change log entry. In particular, comments usually will not say why some
code was deleted or moved to another place--that belongs to the
description of the change which did that.
Following the free-text description of the change, it is a good idea
to give a list of names of the entities or definitions that you changed,
according to the files they are in, and what was changed in each one.
*Note Style of Change Logs::. If a project uses a modern VCS to keep
the change log information, as described in *note Change Logs::,
explicitly listing the files and functions that were changed is not
strictly necessary, and in some cases (like identical mechanical changes
in many places) even tedious. It is up to you to decide whether to
allow your project's developers to omit the list of changed files and
functions from the log entries, and whether to allow such omissions
under some specific conditions. However, while making this decision,
please consider the following benefits of providing the list of changed
entities with each change:
* Generation of useful 'ChangeLog' files from VCS logs becomes more
difficult if the change log entries don't list the modified
functions/macros, because VCS commands cannot reliably reproduce
their names from the commit information alone. For example, when
there is a change in the header part of a function definition, the
heading of the diff hunk as shown in the VCS log commands will name
the wrong function as being modified (usually, the function defined
before the one being modified), so using those diffs to glean the
names of the modified functions will produce inaccurate results.
You will need to use specialized scripts, such as
'gitlog_to_changelog.py', mentioned below, to solve these
difficulties, and make sure it supports the source languages used
by your project.
* While modern VCS commands, such as Git's 'git log -L' and 'git log
-G', provide powerful means for finding changes that affected a
certain function or macro or data structure (and thus might make
'ChangeLog' files unnecessary if you have the repository
available), they can sometimes fail. For example, 'git log -L'
doesn't support syntax of some programming languages out of the
box. Mentioning the modified functions/macros explicitly allows
finding the related changes simply and reliably.
* Some VCS commands have difficulties or limitations when tracking
changes across file moves or renames. Again, if the entities are
mentioned explicitly, those difficulties can be overcome.
* Users that review changes using the generated 'ChangeLog' files may
not have the repository and the VCS commands available to them.
Naming the modified entities alleviates that problem.
For these reasons, providing lists of modified files and functions with
each change makes the change logs more useful, and we therefore
recommend to include them whenever possible and practical.
It is also possible to generate the lists naming the modified
entities by running a script. One such script is
'gitlog_to_changelog.py' (written in Python 3); it is used by the
'glibc' project. Note that this currently supports fewer programming
languages than the manual commands provided by Emacs (*note Style of
Change Logs::).
File: standards.info, Node: Style of Change Logs, Next: Simple Changes,
Prev: Change Log Concepts, Up: Change Logs
6.8.2 Style of Change Logs
--------------------------
Here are some simple examples of change log entries, starting with the
header line that says who made the change and when it was installed,
followed by descriptions of specific changes. (These examples are drawn
from Emacs.) Keep in mind that the line which shows the date of the
change and the author's name and email address is needed only in a
separate 'ChangeLog' file, not when the change logs are kept in a VCS.
2019-08-29 Noam Postavsky <[email protected]>
Handle completely undecoded input in term (Bug#29918)
* lisp/term.el (term-emulate-terminal): Avoid errors if the whole
decoded string is eight-bit characters. Don't attempt to save the
string for next iteration in that case.
* test/lisp/term-tests.el (term-decode-partial)
(term-undecodable-input): New tests.
2019-06-15 Paul Eggert <[email protected]>
Port to platforms where tputs is in libtinfow
* configure.ac (tputs_library): Also try tinfow, ncursesw
(Bug#33977).
2019-02-08 Eli Zaretskii <[email protected]>
Improve documentation of 'date-to-time' and 'parse-time-string'
* doc/lispref/os.texi (Time Parsing): Document
'parse-time-string', and refer to it for the description of
the argument of 'date-to-time'.
* lisp/calendar/time-date.el (date-to-time): Refer in the doc
string to 'parse-time-string' for more information about the
format of the DATE argument. (Bug#34303)
If you mention the names of the modified functions or variables, it's
important to name them in full. Don't abbreviate function or variable
names, and don't combine them. Subsequent maintainers will often search
for a function name to find all the change log entries that pertain to
it; if you abbreviate the name, they won't find it when they search.
For example, some people are tempted to abbreviate groups of function
names by writing '* register.el ({insert,jump-to}-register)'; this is
not a good idea, since searching for 'jump-to-register' or
'insert-register' would not find that entry.
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
')', rather than ',', and opening the continuation with '(' as in this
example:
* src/keyboard.c (menu_bar_items, tool_bar_items)
(Fexecute_extended_command): Deal with 'keymap' property.
The easiest way to add an entry to 'ChangeLog' is with the Emacs
command 'M-x add-change-log-entry', or its variant 'C-x 4 a'
('add-change-log-entry-other-window'). This automatically collects the
name of the changed file and the changed function or variable, and
formats a change log entry according to the conventions described above,
leaving it up to you to describe the changes you made to that function
or variable.
When you install someone else's changes, put the contributor's name
in the change log entry rather than in the text of the entry. In other
words, write this:
2002-07-14 John Doe <[email protected]>
* sewing.c: Make it sew.
rather than this:
2002-07-14 Usual Maintainer <[email protected]>
* sewing.c: Make it sew. Patch by [email protected].
When committing someone else's changes into a VCS, use the VCS
features to specify the author. For example, with Git, use 'git commit
--author=AUTHOR'.
As for the date, that should be the date you applied the change.
(With a VCS, use the appropriate command-line switches, e.g., 'git
commit --date=DATE'.)
Modern VCS have commands to apply changes sent via email (e.g., Git
has 'git am'); in that case the author of the changeset and the date it
was made will be automatically gleaned from the email message and
recorded in the repository. If the patches are prepared with suitable
VCS commands, such as 'git format-patch', the email message body will
also have the original author of the changeset, so resending or
forwarding the message will not interfere with attributing the changes
to their author. Thus, we recommend that you request your contributors
to use commands such as 'git format-patch' to prepare the patches.
