From 94991ea31eb40f9cca525358de6eead0bad779d0 Mon Sep 17 00:00:00 2001
From: Jim Klimov <jimklimov+nut@gmail.com>
Date: Tue, 16 Jul 2024 11:58:26 +0200
Subject: [PATCH] Makefile.am, NEWS.adoc, UPGRADING.adoc: for ChangeLog
 generation from git metadata, default to
 HANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR=true [#2510]

Signed-off-by: Jim Klimov <jimklimov+nut@gmail.com>
---
 Makefile.am    | 10 ++++++++--
 NEWS.adoc      |  9 +++++++++
 UPGRADING.adoc |  7 +++++++
 3 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 0ba1eeefb5..622bc6a231 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -359,7 +359,11 @@ endif
 # repo configuration, or submodules). But this is a Git-crawling target
 # anyway, and in the worst case (Git's design changes) we would spend a
 # bit of time researching the FS in vain, and go on to re-generate the
-# ChangeLog when maybe we should not have - oh well:
+# ChangeLog when maybe we should not have - oh well.
+# WARNING: The CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR=true mode here is
+# default to allow for prettier documentation, but it can require too much
+# memory for weaker build systems. Set it to false when calling make there.
+CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR_ENVVAR = true
 $(abs_top_builddir)/ChangeLog: tools/gitlog2changelog.py dummy-stamp
 	@cd $(abs_top_srcdir) && \
 	    if test -e .git ; then \
@@ -369,7 +373,9 @@ $(abs_top_builddir)/ChangeLog: tools/gitlog2changelog.py dummy-stamp
 	            echo "Using still-valid ChangeLog file generated earlier from same revision of Git source metadata in '$${NUT_GITDIR}'" >&2 ; \
 	        else \
 	            echo "  DOC-CHANGELOG-GENERATE        $@" ; \
-	            CHANGELOG_FILE="$@" $(WITH_PDF_NONASCII_TITLES_ENVVAR) $(abs_top_builddir)/tools/gitlog2changelog.py $(GITLOG_START_POINT) || { \
+	            CHANGELOG_FILE="$@" $(WITH_PDF_NONASCII_TITLES_ENVVAR) \
+	            CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR="$(CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR_ENVVAR)" \
+	              $(abs_top_builddir)/tools/gitlog2changelog.py $(GITLOG_START_POINT) || { \
 	                echo "  DOC-CHANGELOG-GENERATE        $@ : FAILED (non-fatal)" >&2 ; \
 	                printf "gitlog2changelog.py failed to generate the ChangeLog.\n\nNOTE: See https://github.com/networkupstools/nut/commits/master for change history.\n\n" > "$@" ; \
 	            } ; \
diff --git a/NEWS.adoc b/NEWS.adoc
index 0ee525b938..6ba1eb092d 100644
--- a/NEWS.adoc
+++ b/NEWS.adoc
@@ -213,6 +213,15 @@ during a NUT build.
  - added a `make distcheck-light-man` recipe to require verification that the
    manual page files can be built using the prepared "tarball" archive. [#2473]
 
+ - revised the documentation building recipes, with the goal to avoid building
+   the `ChangeLog` products and their intermediate files more than once (but
+   still react to `git` metadata changes during development), and to sanity
+   check the resulting final document (currently only for `html-single` mode).
+   As part of this, the `CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR` setting was
+   added (for `make` calls and used by `tools/gitlog2changelog.py.in` script),
+   and it defaults to `true` allowing for better ordered documents at the cost
+   of some memory during document generation. [#2510]
+
  - added a `common/Makefile.am` build product for a new internal library
    `libcommonstr.la` which allows a smaller selection of helper methods
    for tools like `nut-scanner` which do not need the full `libcommon.la`
diff --git a/UPGRADING.adoc b/UPGRADING.adoc
index 7580eda30e..16c8673c55 100644
--- a/UPGRADING.adoc
+++ b/UPGRADING.adoc
@@ -38,6 +38,13 @@ Changes from 2.8.2 to 2.8.3
   pages which are delivered automatically. Packaging recipes can likely
   be simplified now. [#2445]
 
+- A `CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR` setting was added (for `make`
+  calls and used by `tools/gitlog2changelog.py.in` script), and it defaults
+  to `true` allowing for better ordered documents at the cost of some memory
+  during document generation. Resource-constrained builders (working from
+  a Git workspace, not tarball archives) may have to set it to `false` when
+  calling `make` for NUT. [#2510]
+
 - NUT products like `nut-scanner`, which dynamically load shared libraries
   at run-time without persistent pre-linking, should now know the library
   file names that were present during build (likely encumbered with version