Re: [PATCH] gitlog-to-changelog: Make output reproducible.

[Simon Josefsson]

Bruno Haible <bruno@clisp.org> writes:

> I don't agree with this patch. It misrepresents the dates on which people
> have checked in their commits.

Paul Eggert <eggert@cs.ucla.edu> writes:

> Emacs has had the tradition of using UTC for ChangeLog dates, so
> please support that as well, as an option. This Emacs tradition dates
> back to the RCS days, as RCS supports only UTC timestamps for
> commits. Because UTC commit dates in ChangeLogs are sorted
> numerically, this lessens confusion for newbie ChangeLog readers.
>
> Although using UTC can be offputtinmg to a somewhat more expert reader
> who prefers dates to use the committer's UTC offset, ChangeLog format
> is not obvious anyway when the line contains the *committer's* date
> but the *author's* name. Projects like Emacs can reasonably prefer the
> confusion of using UTC, to the confusion of dates that seem to be out
> of order.

My head keeps spinning trying to figure out what the proper behaviour
should be, so I have reverted my patch and added documentation for the
current behaviour.  Documentation on the Makefile.am snippet was lacking
and seems useful on its own, I suspect people copied it from some other
project that used gitlog-to-changelog and the snippet was never
documented anywhere (or did I miss that?).  Now documentation mention
how to disable locale-dependent behaviour, for those who desire that.  I
still think it is bad to have output of gitlog-to-changelog depend on
the locale, but I'm not sure what the real intended behaviour really
should be (is time zone handling even non-ambigious from the GNU
standards document?) or what different project maintainers would prefer.
As you suggest with Emacs, maybe there are different expectations in
different projects.

/Simon

From 02d2ae07d9f72d73de615498218a7995de98a201 Mon Sep 17 00:00:00 2001
From: Simon Josefsson <simon@josefsson.org>
Date: Mon, 15 Apr 2024 17:47:52 +0200
Subject: [PATCH] gitlog-to-changelog: Revert 2024-04-12 fix and add
 documentation.

* build-aux/gitlog-to-changelog: Use localtime.
* doc/gitlog-to-changelog.texi: Add.
* doc/gnulib.texi (Build Infrastructure Modules): Add.
---
 ChangeLog                     |  7 +++
 build-aux/gitlog-to-changelog |  4 +-
 doc/gitlog-to-changelog.texi  | 81 +++++++++++++++++++++++++++++++++++
 doc/gnulib.texi               |  3 ++
 4 files changed, 93 insertions(+), 2 deletions(-)
 create mode 100644 doc/gitlog-to-changelog.texi

diff --git a/ChangeLog b/ChangeLog
index 5b7b3a36fc..2ab6e41ae2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2024-04-15  Simon Josefsson  <simon@josefsson.org>
+
+       gitlog-to-changelog: Revert 2024-04-12 fix and add documentation.
+       * build-aux/gitlog-to-changelog: Use localtime.
+       * doc/gitlog-to-changelog.texi: Add.
+       * doc/gnulib.texi (Build Infrastructure Modules): Add.
+
 2024-04-14  Collin Funk  <collin.funk1@gmail.com>
 
        gnulib-tool.py: Fix incorrect type hint.
diff --git a/build-aux/gitlog-to-changelog b/build-aux/gitlog-to-changelog
index e06106490c..16a9405a7c 100755
--- a/build-aux/gitlog-to-changelog
+++ b/build-aux/gitlog-to-changelog
@@ -35,7 +35,7 @@
 eval 'exec perl -wSx "$0" "$@"'
      if 0;
 
-my $VERSION = '2024-04-12 15:23'; # UTC
+my $VERSION = '2023-06-24 21:59'; # UTC
 # The definition above must lie within the first 8 lines in order
 # for the Emacs time-stamp write hook (at end) to update it.
 # If you change this file with Emacs, please let the write hook
@@ -360,7 +360,7 @@ sub git_dir_option($)
                   ? '  (tiny change)' : '');
 
       my $date_line = sprintf "%s  %s$tiny\n",
-        strftime ("%Y-%m-%d", gmtime ($1)), $2;
+        strftime ("%Y-%m-%d", localtime ($1)), $2;
 
       my @coauthors = grep /^Co-authored-by:.*$/, @line;
       # Omit meta-data lines we've already interpreted.
diff --git a/doc/gitlog-to-changelog.texi b/doc/gitlog-to-changelog.texi
new file mode 100644
index 0000000000..137b15fcda
--- /dev/null
+++ b/doc/gitlog-to-changelog.texi
@@ -0,0 +1,81 @@
+@node gitlog-to-changelog
+@section gitlog-to-changelog
+
+@c Copyright (C) 2024 Free Software Foundation, Inc.
+
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3 or
+@c any later version published by the Free Software Foundation; with no
+@c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+@c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
+
+@cindex gitlog
+@cindex changelog
+
+Gnulib have a module @code{gitlog-to-changelog} to parse @code{git log}
+output and generate @code{ChangeLog} files, see
+@ifinfo
+@ref{Change Logs,,,standards}.
+@end ifinfo
+@ifnotinfo
+@url{https://www.gnu.org/prep/standards/html_node/Change-Logs.html}.
+@end ifnotinfo
+
+You would typically use it by extending the @code{dist-hook} in the
+top-level @code{Makefile.am} like this:
+
+@example
+dist-hook: gen-ChangeLog
+...
+.PHONY: gen-ChangeLog
+gen-ChangeLog:
+        $(AM_V_GEN)if test -e .git; then                               \
+                $(top_srcdir)/build-aux/gitlog-to-changelog >          \
+                        $(distdir)/cl-t &&                             \
+                @{ rm -f $(distdir)/ChangeLog &&                        \
+                  mv $(distdir)/cl-t $(distdir)/ChangeLog; @}           \
+        fi
+@end example
+
+See @code{gitlog-to-changelog --help} for complete documentation.
+
+The tool prints timestamps using @code{localtime}, so its output may be
+different depending on what locale the developer that runs the tool is
+using.  If your project desire reproducible ChangeLog files that doesn't
+depend on locale settings, use something like the following.
+
+@example
+gen-ChangeLog:
+        $(AM_V_GEN)if test -e .git; then                               \
+                env LC_ALL=en_US.UTF-8 TZ=UTC=0                        \
+                        $(top_srcdir)/build-aux/gitlog-to-changelog >  \
+                        $(distdir)/cl-t &&                             \
+                @{ rm -f $(distdir)/ChangeLog &&                        \
+                  mv $(distdir)/cl-t $(distdir)/ChangeLog; @}           \
+        fi
+@end example
+
+
+If you wish to limit the ChangeLog entries (perhaps for size issues) to
+only contain entries since a particular git tag, use something like the
+following:
+
+@example
+dist-hook: gen-ChangeLog
+...
+gen_start_ver = 8.31
+.PHONY: gen-ChangeLog
+gen-ChangeLog:
+        $(AM_V_GEN)if test -e .git; then                               \
+          log_fix="$(srcdir)/build-aux/git-log-fix";                   \
+          test -e "$$log_fix"                                          \
+            && amend_git_log="--amend=$$log_fix"                       \
+            || amend_git_log=;                                         \
+          $(top_srcdir)/build-aux/gitlog-to-changelog $$amend_git_log  \
+            -- v$(gen_start_ver)~.. > $(distdir)/cl-t &&               \
+            @{ printf '\n\nSee the source repo for older entries\n'     \
+              >> $(distdir)/cl-t &&                                    \
+              rm -f $(distdir)/ChangeLog &&                            \
+              mv $(distdir)/cl-t $(distdir)/ChangeLog; @}               \
+        fi
+@end example
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 45bdf79662..ac8c01d1e1 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -7062,6 +7062,7 @@ for use with GNU Automake (in particular).
 * manywarnings::
 * Running self-tests under valgrind::
 * VCS To ChangeLog::
+* gitlog-to-changelog::
 @end menu
 
 @include havelib.texi
@@ -7080,6 +7081,8 @@ for use with GNU Automake (in particular).
 
 @include vcs-to-changelog.texi
 
+@include gitlog-to-changelog.texi
+
 
 @node Build Infrastructure Files
 @chapter Build Infrastructure Files
-- 
2.34.1

signature.asc
Description: PGP signature