[Emacs-diffs] emacs-24 01/01: Lessen focus on ChangeLog files, as opposed to change log entries.

[Paul Eggert]

branch: emacs-24
commit cd2e816cd3ebf562c680ed15b53cf2a88a01f14f
Author: Paul Eggert <address@hidden>
Date:   Wed Nov 19 11:29:40 2014 -0800

    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.
---
 admin/ChangeLog            |   10 ++++++++++
 admin/notes/bugtracker     |    6 +++---
 admin/notes/changelogs     |   23 -----------------------
 admin/notes/copyright      |    6 +++---
 admin/notes/newfile        |    2 +-
 admin/notes/repo           |   33 +++++++++++++++++++++++++++------
 doc/emacs/ChangeLog        |    7 +++++++
 doc/emacs/maintaining.texi |    8 +++++---
 doc/emacs/trouble.texi     |    6 +++---
 doc/lispref/ChangeLog      |    6 ++++++
 doc/lispref/intro.texi     |    2 +-
 doc/lispref/tips.texi      |    6 +++---
 etc/CONTRIBUTE             |   16 +++++++++++++---
 etc/ChangeLog              |    6 ++++++
 14 files changed, 88 insertions(+), 49 deletions(-)

diff --git a/admin/ChangeLog b/admin/ChangeLog
index 0ec6d92..82974dc 100644
--- a/admin/ChangeLog
+++ b/admin/ChangeLog
@@ -1,3 +1,13 @@
+2014-11-19  Paul Eggert  <address@hidden>
+
+       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  <address@hidden>
 
        * admin/CPP-DEFINES: Mention MINGW_W64.
diff --git a/admin/notes/bugtracker b/admin/notes/bugtracker
index 3d9df20..fd7bd08 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 1025cfc..0000000
--- 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 74aa73b..c5452c3 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 0b66b80..a682fec 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 ded1032..46a9e08 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 a72c2a8..e307ff3 100644
--- a/doc/emacs/ChangeLog
+++ b/doc/emacs/ChangeLog
@@ -1,3 +1,10 @@
+2014-11-19  Paul Eggert  <address@hidden>
+
+       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  <address@hidden>
 
        * maintaining.texi (Switching Branches): Mention "C-x v r".
diff --git a/doc/emacs/maintaining.texi b/doc/emacs/maintaining.texi
index fef3cde..dd1c826 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 09260a1..5f3cf92 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
address@hidden 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.
address@hidden 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 9123194..363e7ae 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,9 @@
+2014-11-19  Paul Eggert  <address@hidden>
+
+       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  <address@hidden>
 
        * Makefile.in (version): Remove variable.
diff --git a/doc/lispref/intro.texi b/doc/lispref/intro.texi
index 0c5346f..1cd79bb 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 d8b906d..f7f07e8 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
address@hidden Log}.
 
 @item ;;; Code:
 This begins the actual code of the program.
diff --git a/etc/CONTRIBUTE b/etc/CONTRIBUTE
index d1ee9f4..b07b6c6 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 851af7f..9f66788 100644
--- a/etc/ChangeLog
+++ b/etc/ChangeLog
@@ -1,3 +1,9 @@
+2014-11-19  Paul Eggert  <address@hidden>
+
+       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  <address@hidden>
 
        Backport fix for minor Bazaar leftovers.