Re: Should we restore manually maintained ChangeLogs

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 1475 bytes --]

Eli Zaretskii wrote:
>> My own experience is otherwise. For the kinds of development I do, I rarely see ChangeLog screwups now, whereas I used to see them routinely.
>
> With or without git-merge-changelog?

Without.  That program is not normally installed.  And I rarely do merges so I 
don't see why it would help.  I recall trying to use it a while ago and had 
trouble (sorry, do not recall details).

> What alternatives that don't "cater to
> all sides" would you suggest?  The only one I see is to stop producing
> ChangeLog files for the releases.

That's what Guile does and it works OK.

If we want to be more traditional and keep ChangeLog files in releases, we can 
do what coreutils etc. do. They autogenerate ChangeLog files for releases, but 
do not put these ChangeLog files in their repositories. They have a way to fix 
typos in the autogenerated ChangeLog files. It works well enough, as long as 
typo fixes are rare enough (which they should be). This is all a bit more 
complicated than what Guile does, but it's simpler than what Emacs does now, and 
it preserves most of the advantages of what Emacs does now.

> Please describe the details of your proposal.

For the more-traditional approach, apply the attached patch to emacs-25, and 
merge it to master.  Other branches can pick it up as needed.

We can easily implement the Guile approach too (it's even simpler), though it 
sounds like you prefer the more-traditional approach, at least for now.

[-- Attachment #2: 0001-Simplify-autogeneration-of-top-level-ChangeLog.patch --]
[-- Type: text/x-diff, Size: 11777 bytes --]

From c49feeacc33772212ebf4c53a05adb169d8b1d9b Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Tue, 8 Mar 2016 23:49:05 -0800
Subject: [PATCH] Simplify autogeneration of top-level ChangeLog

Use the simpler approach of coreutils, etc.  Do not maintain
ChangeLog files in the repository (except for files already
present, which are grandfathered in).  Insted, generate a
ChangeLog file when making a distribution tarball.  Any typos
in the generated ChangeLog file can be fixed by editing the
new file build-aux/git-log-fix.
* CONTRIBUTE (Commit messages):
* admin/make-tarball.txt:
* admin/notes/repo (Maintaining ChangeLog history):
Adjust documentation accordingly.
* Makefile.in (emacslog, CHANGELOG_N, emacs-25-branch-is-current)
(unchanged-history-files, new_commit_regexp)
(change-history-nocommit, change-history, change-history-commit):
Remove; no longer needed.
(gen-ChangeLog): Use an approach like Coreutils.  Rename from
ChangeLog, for consistency with coreutils.
* admin/update_autogen (usage, changelog_flag):
Remove -H option, since update_autogen no longer updates ChangeLog.
* build-aux/git-log-fix: New file, with format copied from coreutils.
* build-aux/gitlog-to-emacslog: New option --amend=FILE.
* make-dist: Adjust to ChangeLog -> gen-ChangeLog renaming.
---
 CONTRIBUTE                   |  5 ++--
 Makefile.in                  | 61 ++++++++++++--------------------------------
 admin/make-tarball.txt       |  4 +--
 admin/notes/repo             | 12 +++------
 admin/update_autogen         | 14 +---------
 build-aux/git-log-fix        | 32 +++++++++++++++++++++++
 build-aux/gitlog-to-emacslog |  6 ++++-
 make-dist                    |  2 +-
 8 files changed, 63 insertions(+), 73 deletions(-)
 create mode 100644 build-aux/git-log-fix

diff --git a/CONTRIBUTE b/CONTRIBUTE
index 5102b4f..878ac8e 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -56,8 +56,9 @@ Here is an example commit message (indented):
 	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
 	Deactivate the mark.
 
-Occasionally, commit messages are collected and prepended to a
-ChangeLog file, where they can be corrected.  It saves time to get
+When generating a release, commit messages are collected into a
+ChangeLog file for the release tarball.  Although errors in these commit
+messages can be fixed (see build-aux/git-log-fix), it saves time to get
 them right the first time, so here are guidelines for formatting them:
 
 - Start with a single unindented summary line explaining the change;
diff --git a/Makefile.in b/Makefile.in
index b212c91..49c133c 100644
--- a/Makefile.in
+++ b/Makefile.in
@@ -1092,54 +1092,25 @@ bootstrap: bootstrap-clean
 	$(MAKE) MAKEFILE_NAME=force-Makefile force-Makefile
 	$(MAKE) all
 
-.PHONY: ChangeLog change-history change-history-commit change-history-nocommit
-.PHONY: emacs-25-branch-is-current unchanged-history-files
-
 CHANGELOG = ChangeLog
-emacslog = build-aux/gitlog-to-emacslog
 # The ChangeLog history files are called ChangeLog.1, ChangeLog.2, ...,
-# ChangeLog.$(CHANGELOG_HISTORY_INDEX_MAX).  $(CHANGELOG_N) stands for
-# the newest (highest-numbered) ChangeLog history file.
+# ChangeLog.$(CHANGELOG_HISTORY_INDEX_MAX).  These files are left over
+# from the old way, where ChangeLogs were kept in the repository.
 CHANGELOG_HISTORY_INDEX_MAX = 2
-CHANGELOG_N = ChangeLog.$(CHANGELOG_HISTORY_INDEX_MAX)
-
-# Convert git commit log to ChangeLog file.  make-dist uses this.
-# I guess this is PHONY so it always updates?
-ChangeLog:
-	$(AM_V_GEN)cd $(srcdir) && \
-	  ./$(emacslog) -o $(CHANGELOG) -n $(CHANGELOG_HISTORY_INDEX_MAX)
-
-# Check that we are in a good state for changing history.
-emacs-25-branch-is-current:
-	git branch | grep -q '^\* emacs-25$$'
-unchanged-history-files:
-	x=$$(git diff-files --name-only $(CHANGELOG_N) $(emacslog)) && \
-	  test -z "$$x"
-
-# Regular expression that matches the newest commit covered by a ChangeLog.
-new_commit_regexp = ^commit [0123456789abcdef]* (inclusive)
-
-# Copy newer commit messages to the start of the ChangeLog history file,
-# and consider them to be older.
-change-history-nocommit: emacs-25-branch-is-current unchanged-history-files
-	-rm -f ChangeLog.tmp
-	$(MAKE) ChangeLog CHANGELOG=ChangeLog.tmp
-	sed '/^This file records repository revisions/,$$d' \
-	  ChangeLog.tmp >$(CHANGELOG_N).tmp
-	new_commit_line=`grep '$(new_commit_regexp)' ChangeLog.tmp` && \
-	sed 's/$(new_commit_regexp).*/'"$$new_commit_line/" \
-	  $(CHANGELOG_N) >>$(CHANGELOG_N).tmp
-	rm ChangeLog.tmp
-	mv $(CHANGELOG_N).tmp $(CHANGELOG_N)
-
-change-history: change-history-nocommit
-	$(MAKE) $@-commit
-
-# If 'make change-history' fails because the newest ChangeLog history
-# file contains invalid text, fix the file by hand and then run
-# 'make change-history-commit'.
-change-history-commit:
-	git commit -m'; make $@' $(CHANGELOG_N) $(emacslog)
+
+# Convert more-recent git commit messages to a ChangeLog file.
+# make-dist uses this.
+.PHONY: gen-ChangeLog
+gen-ChangeLog:
+	$(AM_V_GEN)if test -d .git; then				\
+	  log_fix="$(srcdir)/build-aux/git-log-fix";			\
+	  test -e "$$log_fix"						\
+	    && amend_git_log="--amend=$$log_fix"			\
+	    || amend_git_log=;						\
+	  $(srcdir)/build-aux/gitlog-to-emacslog			\
+	    -f -n $(CHANGELOG_HISTORY_INDEX_MAX) -o $(CHANGELOG)	\
+	    $$amend_git_log;						\
+	fi
 
 .PHONY: check-declare
 
diff --git a/admin/make-tarball.txt b/admin/make-tarball.txt
index 030ad4c..68d0209 100644
--- a/admin/make-tarball.txt
+++ b/admin/make-tarball.txt
@@ -38,8 +38,8 @@ General steps (for each step, check for possible errors):
       M-x authors RET
 
     If there is an "*Authors Errors*" buffer, address the issues.
-    If there was a ChangeLog typo, run "make change-history" and then
-    fix the newest ChangeLog history file.  If a file was deleted or
+    If there was an important ChangeLog typo, edit
+    build-aux/git-log-fix to fix it.  If a file was deleted or
     renamed, consider adding an appropriate entry to
     authors-ignored-files, authors-valid-file-names, or
     authors-renamed-files-alist.
diff --git a/admin/notes/repo b/admin/notes/repo
index 3ab3da7..bd0d15a 100644
--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -124,13 +124,7 @@ ChangeLog.2, etc., and can be edited just as any other source files
 can.  Newer ChangeLog entries are stored in the repository as commit
 messages, which cannot be edited directly.
 
-'make ChangeLog' copies newer ChangeLog entries into a file
+'make gen-ChangeLog' copies newer ChangeLog entries into a file
 'ChangeLog' that is intended to be put into the distribution tarball.
-This ChangeLog file is not put into the repository.
-
-'make change-history' copies all newer ChangeLog entries into the
-start of the newest ChangeLog history file.  These ChangeLog entries
-are thereafter considered to be old, so later uses of 'make ChangeLog'
-and/or 'make change-history' will no longer copy the entries.  To
-alter ChangeLog history, run 'make change-history', then edit
-the ChangeLog history files manually and commit your changes.
+This ChangeLog file is not put into the repository.  To correct an
+error in a newer ChangeLog entry, edit build-aux/git-log-fix.
diff --git a/admin/update_autogen b/admin/update_autogen
index 199a3aa..7065e22 100755
--- a/admin/update_autogen
+++ b/admin/update_autogen
@@ -69,7 +69,6 @@ Options:
     commit them (caution).
 -q: be quiet; only give error messages, not status messages.
 -A: only update autotools files, copying into specified dir.
--H: also update ChangeLog.${changelog_n}
 -I: also update info/dir.
 -L: also update ldefs-boot.el.
 -C: start from a clean state.  Slower, but more correct.
@@ -88,7 +87,6 @@ autogendir=                     # was "autogen"
 ldefs_flag=1
 lboot_flag=
 info_flag=
-changelog_flag=
 
 ## Parameters.
 ldefs_in=lisp/loaddefs.el
@@ -117,7 +115,7 @@ tempfile=/tmp/$PN.$$
 trap "rm -f $tempfile 2> /dev/null" EXIT
 
 
-while getopts ":hcfqA:HCIL" option ; do
+while getopts ":hcfqA:CIL" option ; do
     case $option in
         (h) usage ;;
 
@@ -133,8 +131,6 @@ while getopts ":hcfqA:HCIL" option ; do
 
         (C) clean=1 ;;
 
-        (H) changelog_flag=1 ;;
-
         (I) info_flag=1 ;;
 
         (L) lboot_flag=1 ;;
@@ -388,14 +384,6 @@ modified=$(status $genfiles $ldefs_out) || die
 commit "loaddefs" $modified || die "commit error"
 
 
-## Less important than the other stuff, so do it last.
-[ ! "$changelog_flag" ] || {
-    make change-history-nocommit || die "make change-history error"
-    modified=$(status $changelog_files) || die
-    commit "ChangeLog" $modified || die "commit error"
-}
-
-
 exit 0
 
 ### update_autogen ends here
diff --git a/build-aux/git-log-fix b/build-aux/git-log-fix
new file mode 100644
index 0000000..8976682
--- /dev/null
+++ b/build-aux/git-log-fix
@@ -0,0 +1,32 @@
+# Changes to automatically-generated ChangeLog
+
+# Copyright 2016 Free Software Foundation, Inc.
+
+# This file is part of GNU Emacs.
+
+# GNU Emacs is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# GNU Emacs is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
+
+
+# This file is expected to be used via gitlog-to-changelog's --amend=FILE
+# option.  It specifies what changes to make to each given SHA1's commit
+# log and metadata, using Perl-eval'able expressions.
+
+# For examples of what you can put into this file, see what Coreutils does:
+# http://git.savannah.gnu.org/cgit/coreutils.git/tree/build-aux/git-log-fix
+
+
+b1abce1a30c66a22766e3d4b8b4ff9ae852f150c
+# This example uniformly replaces one phrase by another, as a test.
+# We can remove this example once this file contains real corrections.
+s/leading space/leading ' '/g
diff --git a/build-aux/gitlog-to-emacslog b/build-aux/gitlog-to-emacslog
index bcc47b1..8d12245 100755
--- a/build-aux/gitlog-to-emacslog
+++ b/build-aux/gitlog-to-emacslog
@@ -25,12 +25,16 @@ export LC_ALL
 # The newest revision that should not appear in the generated ChangeLog.
 gen_origin=
 
+# Whether to amend the git log.  The default is no amendments.
+amend_git_log=--amend=/dev/null
+
 force=
 output=ChangeLog
 nmax=2
 
 while [ $# -gt 0 ]; do
   case "$1" in
+      --amend=*) amend_git_log=$1 ;;
       -g|--gen-origin) gen_origin="$2" ; shift ;;
       -f|--force) force=1 ;;
       -n|--nmax) nmax="$2"; shift ;;
@@ -78,7 +82,7 @@ test -d .git || {
 # See eg the cairo-related ones.
 ./build-aux/gitlog-to-changelog \
     --ignore-matching="^; |^Merge branch '(master|emacs-[0-9][0-9])' of git\.(savannah|sv)\.gnu\.org:/srv/git/emacs$|^Merge remote-tracking branch '.*'$" \
-  --ignore-line='^; ' --format='%B' \
+  --ignore-line='^; ' --format='%B' "$amend_git_log" \
   "$gen_origin..$new_origin" >"ChangeLog.tmp" || exit
 
 if test -s "ChangeLog.tmp"; then
diff --git a/make-dist b/make-dist
index 1cd1a50..9fa20c4 100755
--- a/make-dist
+++ b/make-dist
@@ -286,7 +286,7 @@ mkdir ${tempdir}
 if [ "$changelog" = yes ]; then
   if test -d .git; then
     echo "Making top-level ChangeLog"
-    make ChangeLog CHANGELOG=${tempdir}/ChangeLog || \
+    make CHANGELOG=${tempdir}/ChangeLog gen-ChangeLog || \
       { x=$?; echo "make ChangeLog FAILED (try --no-changelog?)" >&2; exit $x; }
   else
     echo "No repository, so omitting top-level ChangeLog"
-- 
2.5.0