Generate a ChangeLog file from commit logs

* .gitignore: Add 'ChangeLog'.
* build-aux/gitlog-to-changelog: New file, from Gnulib.
* build-aux/gitlog-to-emacslog: New file.
* CONTRIBUTE: Document the revised workflow.
* Makefile.in (clean): Remove *.tmp and etc/*.tmp*
instead of just special cases.
(CHANGELOG_HISTORY_INDEX_MAX, CHANGELOG_N, gen_origin): New vars.
(ChangeLog, unchanged-history-files, change-history)
(change-history-commit): New rules.
* admin/admin.el (make-manuals-dist--1):
Don't worry about doc/ChangeLog.
* admin/authors.el: Add a FIXME.
* admin/make-tarball.txt:
* lisp/calendar/icalendar.el:
* lisp/gnus/deuglify.el:
* lisp/obsolete/gulp.el:
* lwlib/README:
Adjust to renamed ChangeLog history files.
* admin/merge-gnulib (GNULIB_MODULES): Add gitlog-to-changelog.
* admin/notes/repo: Call it 'master' a la Git, not 'trunk' a la Bzr.
Remove obsolete discussion of merging ChangeLog files.
New section "Maintaining ChangeLog history".
* build-aux/git-hooks/pre-commit:
Reject attempts to commit files named 'ChangeLog'.
* lib/gnulib.mk, m4/gnulib-comp.m4: Regenerate.
* make-dist: Make and distribute top-level ChangeLog if there's a
.git directory.  Distribute the new ChangeLog history files
instead of scattered ChangeLog files.  Distribute the new files
gitlog-to-changelog and gitlog-to-emacslog.
Fixes: bug#19113

1 files changed, 63 insertions, 22 deletions

diff --git a/CONTRIBUTE b/CONTRIBUTE
index 005ca17a4e..5c8058a49b 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -32,22 +32,33 @@ entry in their name, not yours. git distinguishes between the author
 and the committer; use the --author option on the commit command to
 specify the actual author; the committer defaults to you.
 
-** commit messages
+** Commit messages
 
-When using git, commit messages should use ChangeLog format, with the
-following modifications:
+Typically, a patch creates ChangeLog entries by putting them into its
+commit message, not by changing a ChangeLog file.  Here is an example
+commit message (indented):
+
+	Deactivate shifted region
+
+	Do not silently extend a region that is not highlighted;
+	this can happen after a shift.
+	* doc/emacs/mark.texi (Shift Selection): Document the change.
+	* lisp/window.el (handle-select-window):
+	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
+	Deactivate the mark.
+	Fixes: bug#19003
+
+The general format is as follows.
 
 - Start with a single unindented summary line explaining the change,
   then an empty line, then unindented ChangeLog entries.
 
-  You can use various Emacs functions to ease this process; see (info
-  "(emacs)Change Log Commands") or
-  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
-
 - Limit lines in commit messages to 78 characters, unless they consist
-  of a single word of at most 140 characters.  If you have trouble
-  fitting the summary into 78 characters, add a summarizing paragraph
-  below the empty line and before the individual file descriptions.
+  of a single word of at most 140 characters; this is enforced by a
+  commit hook.  It's nicer to limit the summary line to 50 characters;
+  this isn't enforced.  If the change can't be summarized so briefly,
+  add a paragraph after the empty line and before the individual file
+  descriptions.
 
 - If only a single file is changed, the summary line can be the normal
   file first line (starting with the asterisk).  Then there is no
@@ -63,8 +74,6 @@ following modifications:
 - Commit messages should not contain the "Signed-off-by:" lines that
   are used in some other projects.
 
-** ChangeLog notes
-
 - Emacs generally follows the GNU coding standards when it comes to
   ChangeLogs:
   http://www.gnu.org/prep/standards/html_node/Change-Logs.html .  One
@@ -83,25 +92,30 @@ following modifications:
   and have a reasonable chance of being read in the future, so it's
   better that they have good presentation.
 
-- There are multiple ChangeLogs in the emacs source; roughly one per
-  high-level directory. The ChangeLog entry for a commit belongs in the
-  lowest ChangeLog that is higher than or at the same level as any file
-  changed by the commit.
-
 - Use the present tense; describe "what the change does", not "what
   the change did".
 
 - 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.
+	* lisp/help.el (view-lossage):
+	* lisp/kmacro.el (kmacro-edit-lossage):
+	* lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300.
 
   (Rather than anything involving "ditto" and suchlike.)
 
-- If the commit fixes a bug, add a separate line
+- If the commit has authors other than yourself, the commit message
+  should contain a separate line like the following:
+
+	Co-authored-by: Joe Schmoe <j.schmoe@example.org>
+
+- If the commit is a tiny change that is exempt from copyright paperwork,
+  the commit message should contain a separate line like the following:
 
-  Fixes: bug#NNNN
+	Copyright-paperwork-exempt: yes
+
+- If the commit fixes a bug, append a separate line
+
+	Fixes: bug#NNNN
 
   where NNNN is the bug number.
 
@@ -119,6 +133,29 @@ following modifications:
   of files such as 'configure'.  "There is no need" means you don't
   have to, but you can if you want to.
 
+- If a commit message's first line starts with "; ", the message is
+  ignored when generating ChangeLog history files via 'make changelog'
+  or via 'make change-history'.  You can use "; " for minor commits
+  that do not need separate ChangeLog entries.
+
+** Generating ChangeLog entries
+
+- You can use various Emacs functions to ease the process of writing
+  ChangeLog entries; see (info "(emacs)Change Log Commands") or
+  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+
+- If you use Emacs VC, one way to format ChangeLog entries is to create
+  a top-level ChangeLog file, and update it with 'C-x 4 a' file as
+  usual.  Do not register the ChangeLog file under git; instead, use
+  'C-c C-a' to insert its contents into into your *vc-log* buffer.
+
+- Alternatively, you can use the vc-dwim command to maintain commit
+  messages.  When you create a source directory, run the shell command
+  'git-changelog-symlink-init' to create a symbolic link from
+  ChangeLog to .git/c/ChangeLog.  Edit this ChangeLog via its symlink
+  with Emacs commands like 'C-x 4 a', and commit the change using the
+  shell command 'vc-dwim --commit'.  Type 'vc-dwim --help' for more.
+
 ** branches
 
 Development normally takes places on the trunk.
@@ -182,6 +219,10 @@ to the tracker at http://debbugs.gnu.org .
 You can subscribe to the mailing lists, or see the list archives,
 by following links from http://savannah.gnu.org/mail/?group=emacs .
 
+To email a patch you can use a shell command like 'git format-patch -1'
+to create a file, and then attach the file to your email.  This nicely
+packages the patch's commit message and changes.
+
 ** Document your changes.
 
 Any change that matters to end-users should have an entry in etc/NEWS.