Collin Funk wrote:
> I've pushed the attached patch. Mostly the same as the original but the
> default behavior is unchanged.
Thanks a lot!
> The option is now named '--commit-timezone'. I'm not very creative so
> feel free to change it if you think of something better. :)
I had nothing better to suggest. Good choice :)
> I added documentation with an example where me and your time zones
> created unordered output in the generated ChangeLog:
>
> 2024-06-19 Bruno Haible <br...@clisp.org>
> 2024-06-18 Collin Funk <collin.fu...@gmail.com>
> 2024-06-19 Bruno Haible <br...@clisp.org>
>
> Hopefully that should make it clear for anyone who wants to avoid that
> behavior.
The doc looks good, except there's no point in showing the bodies of the
three ChangeLog entries.
I like in particular that you start the description with
"If you wish to output the @file{ChangeLog} with dates respecting the
time zone each individual commit was made in you can use ..."
This is exactly right:
* First, show *what* the user can achieve with a certain feature / why
they should use it.
* Second, show *how* the user can achieve it.
Because it allows the user to stop reading once they know that is not
their goal / their use-case.
2024-07-04 Bruno Haible <br...@clisp.org>
gitlog-to-changelog: Tweak documentation.
* doc/gitlog-to-changelog.texi (gitlog-to-changelog): Omit irrelevant
detail.
diff --git a/doc/gitlog-to-changelog.texi b/doc/gitlog-to-changelog.texi
index 2b96721e5d..6f1cabdcaf 100644
--- a/doc/gitlog-to-changelog.texi
+++ b/doc/gitlog-to-changelog.texi
@@ -61,31 +61,24 @@
The use of @option{--commit-timezone} means that @file{ChangeLog} dates
correctly represent when a committer pushed a change according to their
time zone. However, as a consequence @file{ChangeLog} dates will no
-longer be monotonically increasing. This behavior may be undesired,
-especially when developers are spread across many different time zones.
+longer be monotonically increasing, if the developers are spread across
+different time zones.
For example, the following three commits were made in a short period of
-time across two different time zones:
+time across two different time zones.
+This behavior may be undesired.
@example
2024-06-19 Bruno Haible <bruno@@clisp.org>
- filemode tests: Tweak.
- * tests/test-filemode.c: Update comment.
- * modules/filemode-tests (Depends-on): Add unistd.
+ ...
2024-06-18 Collin Funk <collin.funk1@@gmail.com>
- filemode: Add tests.
- * modules/filemode-tests: New file.
- * tests/test-filemode.c: New file.
+ ...
2024-06-19 Bruno Haible <bruno@@clisp.org>
- copysignl tests: Avoid failure on Solaris 11.4.
- * tests/test-copysignl.c: Include <float.h>.
- (LDBL_BYTES): New macro.
- (main): Use it instead of sizeof (long double).
- * modules/copysignl-tests (Depends-on): Add float.
+ ...
@end example
If you wish to limit the @file{ChangeLog} entries (perhaps for size
