From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: Re: Should we restore manually maintained ChangeLogs Date: Tue, 8 Mar 2016 23:58:07 -0800 Organization: UCLA Computer Science Department Message-ID: <56DFD78F.40205@cs.ucla.edu> References: <56BE7E37.3090708@cs.ucla.edu> <4hd1rw1ubr.fsf@fencepost.gnu.org> <83vb50wxhv.fsf@gnu.org> <87y49vz4cg.fsf@acer.localhost.com> <87vb4zb0i4.fsf@gnu.org> <837fheuu6a.fsf@gnu.org> <83twkiteb3.fsf@gnu.org> <83lh5utbxb.fsf@gnu.org> <56DDD02A.20809@cs.ucla.edu> <83fuw2t2ue.fsf@gnu.org> <56DE0F6A.6010207@cs.ucla.edu> <83pov5rmt6.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="------------040308030905040201090800" X-Trace: ger.gmane.org 1457510334 2494 80.91.229.3 (9 Mar 2016 07:58:54 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 9 Mar 2016 07:58:54 +0000 (UTC) Cc: mthl@gnu.org, johnw@gnu.org, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Mar 09 08:58:40 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1adZ0v-000315-Gx for ged-emacs-devel@m.gmane.org; Wed, 09 Mar 2016 08:58:37 +0100 Original-Received: from localhost ([::1]:39708 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1adZ0v-0001f0-3Z for ged-emacs-devel@m.gmane.org; Wed, 09 Mar 2016 02:58:37 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54843) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1adZ0f-0001e4-9V for emacs-devel@gnu.org; Wed, 09 Mar 2016 02:58:23 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1adZ0d-0006DT-8e for emacs-devel@gnu.org; Wed, 09 Mar 2016 02:58:21 -0500 Original-Received: from zimbra.cs.ucla.edu ([131.179.128.68]:50426) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1adZ0Z-0006CR-0V; Wed, 09 Mar 2016 02:58:15 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 85FE8160E8A; Tue, 8 Mar 2016 23:58:13 -0800 (PST) Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10032) with ESMTP id 55SeEvj52Gis; Tue, 8 Mar 2016 23:58:11 -0800 (PST) Original-Received: from localhost (localhost [127.0.0.1]) by zimbra.cs.ucla.edu (Postfix) with ESMTP id 8AC11160E8F; Tue, 8 Mar 2016 23:58:11 -0800 (PST) X-Virus-Scanned: amavisd-new at zimbra.cs.ucla.edu Original-Received: from zimbra.cs.ucla.edu ([127.0.0.1]) by localhost (zimbra.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10026) with ESMTP id 8PKIkBTLvYIe; Tue, 8 Mar 2016 23:58:11 -0800 (PST) Original-Received: from [192.168.1.9] (pool-100-32-155-148.lsanca.fios.verizon.net [100.32.155.148]) by zimbra.cs.ucla.edu (Postfix) with ESMTPSA id 5E783160E8A; Tue, 8 Mar 2016 23:58:11 -0800 (PST) User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.6.0 In-Reply-To: <83pov5rmt6.fsf@gnu.org> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 131.179.128.68 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:201233 Archived-At: This is a multi-part message in MIME format. --------------040308030905040201090800 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit 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. --------------040308030905040201090800 Content-Type: text/x-diff; name="0001-Simplify-autogeneration-of-top-level-ChangeLog.patch" Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename*0="0001-Simplify-autogeneration-of-top-level-ChangeLog.patch" >From c49feeacc33772212ebf4c53a05adb169d8b1d9b Mon Sep 17 00:00:00 2001 From: Paul Eggert 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 . + + +# 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 --------------040308030905040201090800--