Re: [PATCH] gitlog-to-changelog: Make output reproducible.
Bruno Haible writes:
> I don't agree with this patch. It misrepresents the dates on which people
> have checked in their commits.
Paul Eggert 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
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
+
+ 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
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 00..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 .
+
+@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 \
+
Re: [PATCH] gitlog-to-changelog: Make output reproducible.
On 2024-04-12 10:54, Simon Josefsson via Gnulib discussion list wrote: I'll try to come up with a fix. 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.
Re: [PATCH] gitlog-to-changelog: Make output reproducible.
fre 2024-04-12 klockan 18:47 +0200 skrev Bruno Haible: > The ChangeLogs are not random data. They are text files meant to be > read > and interpreted by humans. Shoving a "let's use GMT for everyone" > attitude > here is not the right way to handle the diversity of time zones. > > There was a problem already before, in gitlog-to-changelog. Namely, > what > if a committer sits in California and the release manager, who > creates the > tarball, sits in England or Germany? The same effect as above would > occur. > But your change now made it even worse: Even the release manager > cannot > override the time zone. > > The real fix, IMO, is to use 'git log --format=fuller', and convert > the CommitDate (*) by removing the time zone. In the example above: > > CommitDate: Sat Mar 16 22:29:02 2024 -0700 > -> 2024-03-16 > > This way, each committer's days will be correctly represented. I agree with this: ChangeLog dates should correspond to the date when it was commited by the commiter, and since ChangeLog entries doesn't carry time zone data by nature it is local time. That approach is also fully reproducible, which was my main concern, and doesn't depend on the release manager's time zone. Indeed neither the old behaviour and the current behaviour follow what I believe you and me agree on. At least the current behaviour is reproducible regardless of release manager time zone. I'll try to come up with a fix. /Simon signature.asc Description: This is a digitally signed message part
Re: [PATCH] gitlog-to-changelog: Make output reproducible.
Hi Simon, > I ran into a reproducability problem in gitlog-to-changelog, and noticed > Guix people had also ran into this and worked around it outside of > gitlog-to-changelog: > > https://issues.guix.gnu.org/70169/#21 > > However I don't think it makes sense for ChangeLog dates to depend on > the timezone under any circumstance. > > One nit may be that I'm not certain the 'git log' command is time zone > dependent, but at least I could reproduce timezone problems before > applying this patch but not after applying it, so I believe the 'git > log' command already was not time zone dependent. Test like this: > > jas@kaka:~/src/gnulib$ build-aux/gitlog-to-changelog > foo > jas@kaka:~/src/gnulib$ TZ=UTC0 build-aux/gitlog-to-changelog > bar > jas@kaka:~/src/gnulib$ diff -ur foo bar > > I have committed this. I don't agree with this patch. It misrepresents the dates on which people have checked in their commits. For example, assume a developer lives in California and makes many commits after 17:00 local time. At some point he then makes a release. If one of his commits was like this one from gnulib on 2024-03-16 (in 'git log --format=fuller' style): commit af32ee824ee18255839f9812b8ed61aa5257a82b Author: Paul Eggert AuthorDate: Sat Mar 16 22:27:48 2024 -0700 Commit: Paul Eggert CommitDate: Sat Mar 16 22:29:02 2024 -0700 renameatu: support RENAME_EXCHANGE on macOS * lib/renameatu.c (renameat2ish, renameatu) [RENAME_SWAP]: Use macOS RENAME_SWAP to implement GNU/Linux RENAME_EXCHANGE. * tests/test-renameatu.c (main): Add a test for RENAME_EXCHANGE. gitlog-to-changelog will now show it as: 2024-03-17 Paul Eggert renameatu: support RENAME_EXCHANGE on macOS * lib/renameatu.c (renameat2ish, renameatu) [RENAME_SWAP]: Use macOS RENAME_SWAP to implement GNU/Linux RENAME_EXCHANGE. * tests/test-renameatu.c (main): Add a test for RENAME_EXCHANGE. The ChangeLogs are not random data. They are text files meant to be read and interpreted by humans. Shoving a "let's use GMT for everyone" attitude here is not the right way to handle the diversity of time zones. There was a problem already before, in gitlog-to-changelog. Namely, what if a committer sits in California and the release manager, who creates the tarball, sits in England or Germany? The same effect as above would occur. But your change now made it even worse: Even the release manager cannot override the time zone. The real fix, IMO, is to use 'git log --format=fuller', and convert the CommitDate (*) by removing the time zone. In the example above: CommitDate: Sat Mar 16 22:29:02 2024 -0700 -> 2024-03-16 This way, each committer's days will be correctly represented. Bruno (*) CommitDate, not AuthorDate, because of the GNU Coding Standards. [1] [1] https://www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
[PATCH] gitlog-to-changelog: Make output reproducible.
Hi
I ran into a reproducability problem in gitlog-to-changelog, and noticed
Guix people had also ran into this and worked around it outside of
gitlog-to-changelog:
https://issues.guix.gnu.org/70169/#21
However I don't think it makes sense for ChangeLog dates to depend on
the timezone under any circumstance.
One nit may be that I'm not certain the 'git log' command is time zone
dependent, but at least I could reproduce timezone problems before
applying this patch but not after applying it, so I believe the 'git
log' command already was not time zone dependent. Test like this:
jas@kaka:~/src/gnulib$ build-aux/gitlog-to-changelog > foo
jas@kaka:~/src/gnulib$ TZ=UTC0 build-aux/gitlog-to-changelog > bar
jas@kaka:~/src/gnulib$ diff -ur foo bar
I have committed this.
/Simon
From dfb71172a46ef41f8cf8ab7ca529c1dd3097a41d Mon Sep 17 00:00:00 2001
From: Simon Josefsson
Date: Fri, 12 Apr 2024 17:25:16 +0200
Subject: [PATCH] gitlog-to-changelog: Make output reproducible.
* build-aux/gitlog-to-changelog: Use gmtime instead of localtime.
---
ChangeLog | 5 +
build-aux/gitlog-to-changelog | 4 ++--
2 files changed, 7 insertions(+), 2 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index cdbb53ff8a..b20f69b06b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2024-04-12 Simon Josefsson
+
+ gitlog-to-changelog: Make output reproducible.
+ * build-aux/gitlog-to-changelog: Use gmtime instead of localtime.
+
2024-04-12 Bruno Haible
gnulib-tool.py: Fix parsing of gl_LGPL in gnulib-cache.m4.
diff --git a/build-aux/gitlog-to-changelog b/build-aux/gitlog-to-changelog
index 16a9405a7c..e06106490c 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 = '2023-06-24 21:59'; # UTC
+my $VERSION = '2024-04-12 15:23'; # 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", localtime ($1)), $2;
+strftime ("%Y-%m-%d", gmtime ($1)), $2;
my @coauthors = grep /^Co-authored-by:.*$/, @line;
# Omit meta-data lines we've already interpreted.
--
2.39.2
signature.asc
Description: PGP signature
