Bruno Haible <br...@clisp.org> writes: > I don't agree with this patch. It misrepresents the dates on which people > have checked in their commits.
Paul Eggert <egg...@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 <si...@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 <si...@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.fu...@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
