Lessen focus on ChangeLog files, as opposed to change log entries.

This is in preparation for generating the former automatically
from the latter.
* admin/notes/bugtracker, admin/notes/copyright, admin/notes/newfile:
ChangeLog -> change log
* admin/notes/changelogs: Remove, merging old contents to ...
* admin/notes/repo: ... here.
* doc/emacs/maintaining.texi (Change Log): Mention that ChangeLog files may
be copied to or from a version control system.
* doc/emacs/trouble.texi (Sending Patches): Point to the commit messages.
* doc/lispref/intro.texi (Acknowledgments): ChangeLog file -> change log entries.
* doc/lispref/tips.texi (Library Headers): Emacs uses a version control system.
* etc/CONTRIBUTE: Give advice about git commit messages and how
to generate proposed patches containing them.

14 files changed, 88 insertions, 49 deletions

diff --git a/admin/ChangeLog b/admin/ChangeLog
index 0ec6d920ad0..82974dc846f 100644
--- a/admin/ChangeLog
+++ b/admin/ChangeLog
@@ -1,3 +1,13 @@
+2014-11-19  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Lessen focus on ChangeLog files, as opposed to change log entries.
+        This is in preparation for generating the former automatically
+        from the latter.
+        * notes/bugtracker, notes/copyright, notes/newfile:
+        ChangeLog -> change log
+        * notes/changelogs: Remove, merging old contents to ...
+        * notes/repo: ... here.
+
 2014-11-17  Oscar Fuentes  <ofv@wanadoo.es>
 
         * admin/CPP-DEFINES: Mention MINGW_W64.
diff --git a/admin/notes/bugtracker b/admin/notes/bugtracker
index 3d9df200f44..fd7bd08091a 100644
--- a/admin/notes/bugtracker
+++ b/admin/notes/bugtracker
@@ -463,10 +463,10 @@ time, rather than by increasing bug number
 
 "raw" = ?
 
-** ChangeLog issues
+** Change log issues
 
 *** When you fix a bug, it can be helpful to put the bug number in the
-ChangeLog entry, for example:
+change log entry, for example:
 
    * foo.el (foofunc): Fix the `foo' case.  (Bug#123)
 
@@ -475,7 +475,7 @@ obvious fix (e.g. a typo), there's no need to clutter the log with the
 bug number.
 
 Similarly, when you close a bug, it can be helpful to include the
-relevant ChangeLog entry in the message to the bug tracker, so people
+relevant change log entry in the message to the bug tracker, so people
 can see exactly what the fix was.
 
 *** bug-reference-mode
diff --git a/admin/notes/changelogs b/admin/notes/changelogs
deleted file mode 100644
index 1025cfc217f..00000000000
--- a/admin/notes/changelogs
+++ /dev/null
@@ -1,23 +0,0 @@
-If installing changes written by someone else, make the ChangeLog
-entry in their name, not yours.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2007-09/msg00793.html
-  There is no need to make change log entries for files such as NEWS,
-  MAINTAINERS, and FOR-RELEASE.
-"There is no need" means you don't have to, but you can if you want to.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2006-12/msg01135.html
-  There is no need to indicate regeneration of files such as configure
-  in ChangeLog.
-
-
-http://lists.gnu.org/archive/html/emacs-devel/2008-11/msg00940.html
-Preferred form for several entries with the same content:
-
-   * help.el (view-lossage):
-   * kmacro.el (kmacro-edit-lossage):
-   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
-
-(Rather than anything involving "ditto" and suchlike.)
diff --git a/admin/notes/copyright b/admin/notes/copyright
index 74aa73b0394..c5452c38037 100644
--- a/admin/notes/copyright
+++ b/admin/notes/copyright
@@ -22,7 +22,7 @@ author to make a non-trivial total. If so, make sure they have an
 assignment. If adding a whole file adjust the copyright statements in
 the file.
 
-2. When installing code written by someone else, the ChangeLog entry
+2. When installing code written by someone else, the commit
 should be in the name of the author of the code, not the person who
 installs it.  Also use commit's "--author" option.
 Do not install any of your own changes in the same commit.
@@ -115,8 +115,8 @@ else it is possible the file should not be in Emacs at all (please
 report!).
 
 Note that it seems painfully clear that one cannot rely on commit logs,
-or even ChangeLogs, for older changes. People often installed changes
-from others, without recording the true authorship.
+or even change log entries, for older changes. People often installed
+changes from others, without recording the true authorship.
 
 [For reference, most of these points were established via email with
 rms, 2007/1, "Copyright years".
diff --git a/admin/notes/newfile b/admin/notes/newfile
index 0b66b8054bb..a682fec72d5 100644
--- a/admin/notes/newfile
+++ b/admin/notes/newfile
@@ -15,7 +15,7 @@ output under the headings "The following files are not valid DOS file
 names:" and "The following resolve to the same DOS file names:" should
 not include any files that end up in the release tarball.
 
-** Make the ChangeLog entry in the name of the author(s), not your own name.
+** Commit in the name of the author(s), not your own name.
 
 ** If appropriate, check that the file compiles OK and that Emacs
 builds fine with it.  Address any compilation warnings.
diff --git a/admin/notes/repo b/admin/notes/repo
index ded10324f63..46a9e08c698 100644
--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -1,9 +1,16 @@
 NOTES ON COMMITTING TO EMACS'S REPOSITORY    -*- outline -*-
 
-* Use DVCS commenting conventions
+* Commit metainformation
 
-Commits should follow the conventions used in all modern distributed
-version-control systems. That is, they should consist of
+** Commit in the author's name
+
+If installing changes written by someone else, commit them in their
+name, not yours.
+
+** Commit message format
+
+Commit messages should follow the conventions used in all modern
+distributed version-control systems. That is, they should consist of
 
 - A self-contained topic line, preferably no more than 75 chars long.
 
@@ -15,6 +22,21 @@ version-control systems. That is, they should consist of
   files, just copy the entries you made in them to the commit message
   after the blank line.)
 
+- Preferred form for several entries with the same content:
+
+   * help.el (view-lossage):
+   * kmacro.el (kmacro-edit-lossage):
+   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
+
+  (Rather than anything involving "ditto" and suchlike.)
+
+** Unnecessary metainformation
+
+There is no need to make separate change log entries for files such as
+NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration of
+files such as 'configure'.  "There is no need" means you don't have
+to, but you can if you want to.
+
 * Commit to the right branch
 
 Development normally takes places on the trunk.
@@ -112,9 +134,9 @@ http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html
 
 [The section on git merge procedure has not yet been written]
 
-Inspect the ChangeLog entries (e.g. in case too many entries have been
+Inspect the change log entries (e.g. in case too many entries have been
 included or whitespace between entries needs fixing). If someone made
-multiple ChangeLog entries on different days in the branch, you may
+multiple change log entries on different days in the branch, you may
 wish to collapse them all to a single entry for that author in the
 trunk (because in the trunk they all appear under the same date).
 Obviously, if there are multiple changes to the same file by different
@@ -166,4 +188,3 @@ again.
 
 This is a semi-automated way to find the revision that introduced a bug.
 Browse `git help bisect' for technical instructions.
-
diff --git a/doc/emacs/ChangeLog b/doc/emacs/ChangeLog
index a72c2a8915c..e307ff3bd3a 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2014-11-19  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Lessen focus on ChangeLog files, as opposed to change log entries.
+        * maintaining.texi (Change Log): Mention that ChangeLog files may
+        be copied to or from a version control system.
+        * trouble.texi (Sending Patches): Point to the commit messages.
+
 2014-11-19  Eli Zaretskii  <eliz@gnu.org>
 
         * maintaining.texi (Switching Branches): Mention "C-x v r".
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index fef3cdea529..dd1c8269096 100644
--- a/doc/emacs/maintaining.texi
+++ b/doc/emacs/maintaining.texi
@@ -1474,9 +1474,11 @@ different revision with @kbd{C-u C-x v v}.
 @cindex change log
   Many software projects keep a @dfn{change log}.  This is a file,
 normally named @file{ChangeLog}, containing a chronological record of
-when and how the program was changed.  Sometimes, there are several
-change log files, each recording the changes in one directory or
-directory tree.
+when and how the program was changed.  Sometimes, these files are
+automatically generated from the change log entries stored in version
+control systems, or are used to generate these change log entries.
+Sometimes, there are several change log files, each recording the
+changes in one directory or directory tree.
 
 @menu
 * Change Log Commands:: Commands for editing change log files.
diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi
index 09260a1e5a9..5f3cf9223eb 100644
--- a/doc/emacs/trouble.texi
+++ b/doc/emacs/trouble.texi
@@ -1137,9 +1137,9 @@ new function, all you need to say about it is that it is new.  If you
 feel that the purpose needs explaining, it probably does---but put the
 explanation in comments in the code.  It will be more useful there.
 
-Please read the @file{ChangeLog} files in the @file{src} and
-@file{lisp} directories to see what sorts of information to put in,
-and to learn the style that we use.  @xref{Change Log}.
+Please look at the change log entries of recent commits to see what
+sorts of information to put in, and to learn the style that we use.
+@xref{Change Log}.
 
 @item
 When you write the fix, keep in mind that we can't install a change that
diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 9123194d7eb..363e7aecd33 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2014-11-19  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Lessen focus on ChangeLog files, as opposed to change log entries.
+        * intro.texi (Acknowledgments): ChangeLog file -> change log entries.
+        * tips.texi (Library Headers): Emacs uses a version control system.
+
 2014-11-09  Glenn Morris  <rgm@gnu.org>
 
         * Makefile.in (version): Remove variable.
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 0c5346fbb63..1cd79bb2265 100644
--- a/doc/lispref/intro.texi
+++ b/doc/lispref/intro.texi
@@ -552,4 +552,4 @@ Trost, Rickard Westman, Jean White, Eduard Wiebe, Matthew Wilding,
 Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
 
   For a more complete list of contributors, please see the relevant
-ChangeLog file in the Emacs sources.
+change log entries in the Emacs source repository.
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index d8b906d3bfe..f7f07e8fb74 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -1062,9 +1062,9 @@ context.
 @item ;;; Change Log:
 This begins an optional log of changes to the file over time.  Don't
 put too much information in this section---it is better to keep the
-detailed logs in a separate @file{ChangeLog} file (as Emacs does),
-and/or to use a version control system.  @samp{History} is an
-alternative to @samp{Change Log}.
+detailed logs in a version control system (as Emacs does) or in a
+separate @file{ChangeLog} file.  @samp{History} is an alternative to
+@samp{Change Log}.
 
 @item ;;; Code:
 This begins the actual code of the program.
diff --git a/etc/CONTRIBUTE b/etc/CONTRIBUTE
index d1ee9f4690c..b07b6c66afe 100644
--- a/etc/CONTRIBUTE
+++ b/etc/CONTRIBUTE
@@ -118,13 +118,23 @@ documentation, i.e. Texinfo files.
 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
 Manual, for how to write good log entries.
 
+When using git, commit messages should use ChangeLog format, with a
+single short line explaining the change, then an empty line, then
+unindented ChangeLog entries.  (Essentially, a commit message should
+be a duplicate of what the patch adds to the ChangeLog files.  We are
+planning to automate this better, to avoid the duplication.)
+
 ** The patch itself.
 
 If you are accessing the Emacs repository, make sure your copy is
-up-to-date (e.g. with `git pull'), then use
+up-to-date (e.g. with 'git pull').  You can commit your changes
+to a private branch and generate a patch from the master version
+by using
+        git format-patch master
+Or you can leave your changes uncommitted and use
         git diff
-Else, use
-        diff -cp OLD NEW
+With no repository, you can use
+        diff -u OLD NEW
 
 ** Mail format.
 
diff --git a/etc/ChangeLog b/etc/ChangeLog
index 851af7f2735..9f66788d282 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,9 @@
+2014-11-19  Paul Eggert  <eggert@cs.ucla.edu>
+
+        Lessen focus on ChangeLog files, as opposed to change log entries.
+        * CONTRIBUTE: Give advice about git commit messages and how
+        to generate proposed patches containing them.
+
 2014-11-13  Paul Eggert  <eggert@cs.ucla.edu>
 
         Backport fix for minor Bazaar leftovers.