From 30c9b3081bb9206f41be49bcd25882d7f9e65372 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 10:49:40 +0200 Subject: [PATCH 01/13] docs/ci-farm-lxc-setup.txt: update link to conflict-aware-ondemand-strategy-plugin Signed-off-by: Jim Klimov --- docs/ci-farm-lxc-setup.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/ci-farm-lxc-setup.txt b/docs/ci-farm-lxc-setup.txt index 6976469200..d531d46380 100644 --- a/docs/ci-farm-lxc-setup.txt +++ b/docs/ci-farm-lxc-setup.txt @@ -840,8 +840,9 @@ Running one agent at a time Another aspect of farm management is that emulation is a slow and intensive operation, so we can not run all agents and execute builds at the same time. -The current solution relies on -https://github.com/jimklimov/conflict-aware-ondemand-retention-strategy-plugin +The current solution relies on the +https://github.com/jenkinsci/conflict-aware-ondemand-strategy-plugin[Conflict-Aware +On Demand Retention Strategy plugin] to allow co-located build agents to "conflict" with each other -- when one picks up a job from the queue, it blocks neighbors from starting; when it is done, another may start. From af579b2076a544c21425492720a8e8dbf91d7a4d Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 12:52:54 +0200 Subject: [PATCH 02/13] configure.ac, docs/Makefile.am, docs/configure.txt, NEWS.adoc, docs/nut.dict: introduce option to "configure --enable-docs-changelog" (or not) Signed-off-by: Jim Klimov --- NEWS.adoc | 3 + configure.ac | 148 ++++++++++++++++++++++++++++++++++++++++++++- docs/Makefile.am | 33 ++++++++-- docs/configure.txt | 10 +++ docs/nut.dict | 3 +- 5 files changed, 189 insertions(+), 8 deletions(-) diff --git a/NEWS.adoc b/NEWS.adoc index 21f433c5b9..d5fd6db789 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -242,6 +242,9 @@ https://github.com/networkupstools/nut/milestone/9 * Option to `configure --enable-docs-man-for-progs-built-only` was added, to differentiate NUT builds that deliver man pages for only built programs (legacy default) or for all of them (as needed for docs sites). [#2976] + * Option to `configure --enable-docs-changelog` was added, specifically + to allow developer iterations to not waste CPU time rebuilding the huge + `ChangeLog*` files whenever their Git index changes. - The `BUILD_TYPE=default-all-errors ci_build.sh` script handling was revised to simplify code, and to default in CI builds to a quicker diff --git a/configure.ac b/configure.ac index d2711a2171..3a8a466eac 100644 --- a/configure.ac +++ b/configure.ac @@ -50,7 +50,7 @@ dnl # Example: NUT_SOURCE_GITREV='2.8.2.695.1-696+g0e00f0777' NUT_SOURCE_GITREV="`NUT_VERSION_QUERY=DESC50 "${srcdir}/tools/gitlog2version.sh" 2>/dev/null`" dnl A true/false (literally) response that can be used for prettier messages -dnl emitted by NUT code. +dnl emitted by NUT code, or make some "auto" configuration choices below. NUT_SOURCE_GITREV_IS_RELEASE="`NUT_VERSION_QUERY=IS_RELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`" NUT_SOURCE_GITREV_IS_PRERELEASE="`NUT_VERSION_QUERY=IS_PRERELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`" @@ -2487,6 +2487,7 @@ NUT_ARG_WITH([docs], [build and install documentation (alias to --with-doc)], [m NUT_ARG_WITH([doc], [build and install documentation (see docs/configure.txt for many variants of the option)], [${nut_with_docs}]) NUT_ARG_ENABLE([docs-man-for-progs-built-only], [build and install man pages (if enabled) only for built programs (yes, default) or all known pages (no)], [yes]) +NUT_ARG_ENABLE([docs-changelog], [(re-)generate ChangeLog* files - and do so whenever git info changes? (default: auto; yes, no, "adoc,html,pdf"...)], [auto]) dnl Different OS distributions have different layouts of man page section dnl numbers. The one we treat as default seems to be most wide-spread, in @@ -3985,6 +3986,151 @@ fi AM_CONDITIONAL(WITH_PDFS, test "${WITH_PDFS}" = "yes") AM_CONDITIONAL(SKIP_PDFS, test "${SKIP_PDFS}" = "yes") +dnl # NUT ChangeLog* files can consume a lot of build time, +dnl # so we want to let developers skip (re-)building them +dnl # if they enable docs and then iterate their code base. +WITH_CHANGELOG_TEXT=no +WITH_CHANGELOG_ADOC=no +WITH_CHANGELOG_HTML_SINGLE=no +WITH_CHANGELOG_HTML_CHUNKED=no +WITH_CHANGELOG_PDF=no + +dnl # Correlate "auto" with some measure of development iterations (quick) vs. release/tarball build (full). Can maintainer-mode be it? +AS_IF([($NUT_SOURCE_GITREV_IS_RELEASE || $NUT_SOURCE_GITREV_IS_PRERELEASE) && test "${nut_enable_docs_changelog}" = auto], + [nut_enable_docs_changelog=yes] +) + +case "${nut_enable_docs_changelog}" in + no|skip) AC_MSG_NOTICE([Requested to not enable WITH_CHANGELOG_*]) + ;; + yes) + AS_IF([test "${nut_with_doc}" != yes], [AC_MSG_ERROR([Can not enable WITH_CHANGELOG_* due to build settings or environment])]) + WITH_CHANGELOG_TEXT=yes + WITH_CHANGELOG_ADOC=yes + AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no], + [WITH_CHANGELOG_HTML_SINGLE=yes], + [AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment])]) + AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no], + [WITH_CHANGELOG_HTML_CHUNKED=yes], + [AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment])]) + AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no], + [WITH_CHANGELOG_PDF=yes], + [AC_MSG_ERROR([Can not enable WITH_CHANGELOG_PDF due to build settings or environment])]) + ;; + auto|yes=auto|"") + AS_IF([test "${nut_with_doc}" = yes], [ + WITH_CHANGELOG_TEXT=yes + WITH_CHANGELOG_ADOC=yes + AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no], + [WITH_CHANGELOG_HTML_SINGLE=yes], + [WITH_CHANGELOG_HTML_SINGLE=no + AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment]) + ]) + AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no], + [WITH_CHANGELOG_HTML_CHUNKED=yes], + [WITH_CHANGELOG_HTML_CHUNKED=no + AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment]) + ]) + AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no], + [WITH_CHANGELOG_PDF=yes], + [WITH_CHANGELOG_PDF=no + AC_MSG_WARN([Can not enable WITH_CHANGELOG_PDF due to build settings or environment]) + ]) + ], [ + AC_MSG_WARN([Can not enable WITH_CHANGELOG_* due to build settings or environment]) + ]) + ;; + *) + AS_IF([test "${nut_with_doc}" = yes], [ + + dnl # Check each complex format desire independently: + case "${nut_enable_docs_changelog}" in + html-single=no*|*,html-single=no*|html-single=skip*|*,html-single=skip*) ;; + html-single*|*,html-single*) + AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no], + [WITH_CHANGELOG_HTML_SINGLE=yes], + [WITH_CHANGELOG_HTML_SINGLE=no + case "${nut_enable_docs_changelog}" in + *html-single=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment]) ;; + *) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment]) ;; + esac + ]) + ;; esac + + case "${nut_enable_docs_changelog}" in + html-chunked=no*|*,html-chunked=no*|html-chunked=skip*|*,html-chunked=skip*) ;; + html-chunked*|*,html-chunked*) + AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no], + [WITH_CHANGELOG_HTML_CHUNKED=yes], + [WITH_CHANGELOG_HTML_CHUNKED=no + case "${nut_enable_docs_changelog}" in + *html-chunked=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment]) ;; + *) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment]) ;; + esac + ]) + ;; esac + + case "${nut_enable_docs_changelog}" in + pdf=no*|*,pdf=no*|pdf=skip*|*,pdf=skip*) ;; + pdf*|*,pdf*) + AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no], + [WITH_CHANGELOG_PDF=yes], + [WITH_CHANGELOG_PDF=no + case "${nut_enable_docs_changelog}" in + *pdf=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_PDF due to build settings or environment]) ;; + *) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_PDF due to build settings or environment]) ;; + esac + ]) + ;; esac + + case "${nut_enable_docs_changelog}" in + adoc=no*|*,adoc=no*) + AS_IF([test "${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" != "nonono"], + [AC_MSG_ERROR([Can not disable WITH_CHANGELOG_ADOC when HTML and/or PDF build is required])]) + ;; + adoc=yes*|*,adoc=yes*|adoc|adoc,*|*,adoc|*,adoc,*) dnl Require enabled + WITH_CHANGELOG_ADOC=yes + ;; + adoc=skip*|*,adoc=skip*|adoc=auto*|*,adoc=auto*|*) + AS_IF([test "${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" = "nonono"], + [WITH_CHANGELOG_ADOC=no], + [case "${nut_enable_docs_changelog}" in + *adoc=skip*) + AC_MSG_WARN([Can not disable WITH_CHANGELOG_ADOC when HTML and/or PDF build is required, so enabling it]) + ;; + esac + WITH_CHANGELOG_ADOC=yes + ]) + ;; + esac + + WITH_CHANGELOG_TEXT=yes + case "${nut_enable_docs_changelog}" in + text=no|*,text=no) + AS_IF([test "${WITH_CHANGELOG_ADOC}${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" != "nononono"], + [AC_MSG_ERROR([Can not disable WITH_CHANGELOG_TEXT when ADOC, HTML and/or PDF build is required])]) + WITH_CHANGELOG_TEXT=no + ;; + text=skip|*,text=skip) + AS_IF([test "${WITH_CHANGELOG_ADOC}${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" = "nononono"], + [WITH_CHANGELOG_TEXT=no] + [AC_MSG_WARN([Can not disable WITH_CHANGELOG_TEXT when ADOC, HTML and/or PDF build is required, so enabling it])]) + ;; + esac + ], [ + AC_MSG_WARN([Can not enable WITH_CHANGELOG_* due to build settings or environment]) + ]) + ;; +esac + +AM_CONDITIONAL(WITH_CHANGELOG_TEXT, test "${WITH_CHANGELOG_TEXT}" = "yes") +AM_CONDITIONAL(WITH_CHANGELOG_ADOC, test "${WITH_CHANGELOG_ADOC}" = "yes") +AM_CONDITIONAL(WITH_CHANGELOG_HTML_SINGLE, test "${WITH_CHANGELOG_HTML_SINGLE}" = "yes") +AM_CONDITIONAL(WITH_CHANGELOG_HTML_CHUNKED, test "${WITH_CHANGELOG_HTML_CHUNKED}" = "yes") +AM_CONDITIONAL(WITH_CHANGELOG_PDF, test "${WITH_CHANGELOG_PDF}" = "yes") + +NUT_REPORT([Would generate ChangeLog* file formats], [text:${WITH_CHANGELOG_TEXT} adoc:${WITH_CHANGELOG_ADOC} html-single:${WITH_CHANGELOG_HTML_SINGLE} html-chunked:${WITH_CHANGELOG_HTML_CHUNKED} pdf:${WITH_CHANGELOG_PDF}]) + dnl NOTE: Sections may be strings, not pure numbers, on some platforms: MAN_SECTION_API="${nut_with_docs_man_section_api}" MAN_SECTION_CFG="${nut_with_docs_man_section_cfg}" diff --git a/docs/Makefile.am b/docs/Makefile.am index 66f68e758d..5e511a29a1 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -150,7 +150,6 @@ EXTRA_DIST += $(ALL_TXT_SRC) $(SHARED_DEPS) $(IMAGE_FILES) \ EXTRA_DIST += sms-brazil-protocol.txt ASCIIDOC_HTML_SINGLE = \ - $(top_builddir)/docs/ChangeLog.html \ user-manual.html \ developer-guide.html \ packager-guide.html \ @@ -160,8 +159,11 @@ ASCIIDOC_HTML_SINGLE = \ cables.html \ FAQ.html +if WITH_CHANGELOG_HTML_SINGLE +ASCIIDOC_HTML_SINGLE += $(top_builddir)/docs/ChangeLog.html +endif + ASCIIDOC_HTML_CHUNKED = \ - $(top_builddir)/docs/ChangeLog.chunked \ user-manual.chunked \ developer-guide.chunked \ packager-guide.chunked \ @@ -171,8 +173,11 @@ ASCIIDOC_HTML_CHUNKED = \ cables.chunked \ FAQ.chunked +if WITH_CHANGELOG_HTML_CHUNKED +ASCIIDOC_HTML_CHUNKED += $(top_builddir)/docs/ChangeLog.chunked +endif + ASCIIDOC_PDF = \ - $(top_builddir)/docs/ChangeLog.pdf \ user-manual.pdf \ developer-guide.pdf \ packager-guide.pdf \ @@ -182,6 +187,20 @@ ASCIIDOC_PDF = \ cables.pdf \ FAQ.pdf +if WITH_CHANGELOG_PDF +ASCIIDOC_PDF += $(top_builddir)/docs/ChangeLog.pdf +endif + +DOC_BUILD_CHANGELOG_TEXT = +if WITH_CHANGELOG_TEXT +DOC_BUILD_CHANGELOG_TEXT += $(top_builddir)/ChangeLog +endif + +DOC_BUILD_CHANGELOG_ADOC = +if WITH_CHANGELOG_ADOC +DOC_BUILD_CHANGELOG_ADOC += $(top_builddir)/ChangeLog.adoc $(top_builddir)/ChangeLog.adoc-parsed $(top_builddir)/ChangeLog.adoc-parsed.latest +endif + # Note: "man" subdir is handled separately via all-local and check-local # for a few goals, and among SUBDIRs directly from the top-level Makefile # due to some potential dependency collisions with parallel builds. @@ -203,17 +222,19 @@ check-local: $(CHECK_LOCAL_TARGETS) # Make sure sources are there for out-of-tree builds: all-local all-am-local \ +$(DOC_BUILD_CHANGELOG_TEXT) $(DOC_BUILD_CHANGELOG_ADOC) \ @DOC_BUILD_LIST@ $(ASCIIDOC_PDF) $(ASCIIDOC_HTML_SINGLE) $(ASCIIDOC_HTML_CHUNKED): $(abs_top_builddir)/docs/.prep-src-docs all-local: +@cd $(builddir)/man && $(MAKE) $(AM_MAKEFLAGS) all-optional # This list is defined by configure script choices and options: -doc: $(abs_top_builddir)/docs/.prep-src-docs @DOC_BUILD_LIST@ +doc: $(abs_top_builddir)/docs/.prep-src-docs $(DOC_BUILD_CHANGELOG_TEXT) $(DOC_BUILD_CHANGELOG_ADOC) @DOC_BUILD_LIST@ # This target can be called by developers to go around the configure -# script choices at their risk (e.g. missing tools are possible): -docs: pdf html-single html-chunked man-man html-man +# script choices at their risk (e.g. missing tools are possible) and +# try to build all documentation file types: +docs: $(DOC_BUILD_CHANGELOG_TEXT) $(DOC_BUILD_CHANGELOG_ADOC) pdf html-single html-chunked man-man html-man all-docs: docs diff --git a/docs/configure.txt b/docs/configure.txt index d57f834a6a..788ee92b0e 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -390,6 +390,16 @@ Are platform man directories named by base number (yes) or by full section name (no), e.g. given a `1m` man page section, install the pages into `man1` or `man1m` directory? + --enable-docs-changelog= + +This option was added specifically to allow developer iterations to not waste +CPU time rebuilding the huge `ChangeLog*` files whenever their Git index +changes. For troubleshooting purposes, this option supports specifying the +list of formats ('text', 'adoc', 'html-single', 'html-chunked', 'pdf') with +optional suffixes to build (empty/'=yes'), consider ('=auto') or not-build +('=no' or '=skip') specific formats; note that some are prerequisites for +others (plain 'text' and prepared 'adoc' are needed to generate HTML and PDF). + Python support ~~~~~~~~~~~~~~ diff --git a/docs/nut.dict b/docs/nut.dict index 5d6ebba974..f048689ac8 100644 --- a/docs/nut.dict +++ b/docs/nut.dict @@ -1,4 +1,4 @@ -personal_ws-1.1 en 3529 utf-8 +personal_ws-1.1 en 3530 utf-8 AAC AAS ABI @@ -1760,6 +1760,7 @@ cgi cgipath cgroup cgroupsv +changelog chargetime charset checkruntime From 1662f1ebf36ec8c17c506247cc58cad8b6589ae3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 13:11:33 +0200 Subject: [PATCH 03/13] ci_build.sh: configure --disable-docs-changelog in developer iterations Signed-off-by: Jim Klimov --- ci_build.sh | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/ci_build.sh b/ci_build.sh index 5a78d0d328..6850a575a0 100755 --- a/ci_build.sh +++ b/ci_build.sh @@ -2566,6 +2566,10 @@ bindings) else # Help developers debug: CONFIG_OPTS+=("--disable-silent-rules") + + # In developer iterations, avoid burning CPU every + # time our git index changes + CONFIG_OPTS+=("--enable-docs-changelog=no") fi if [ -z "${WITH_UNMAPPED_DATAPOINTS-}" ] ; then From fb4abf0e3d5a55d675f7a274321f0278c60eb9f7 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 13:55:10 +0200 Subject: [PATCH 04/13] configure.ac, Makefile.am, docs/configure.txt, NEWS.adoc: introduce confgure option to customize git log starting point Signed-off-by: Jim Klimov --- Makefile.am | 3 ++- NEWS.adoc | 8 ++++++++ configure.ac | 29 ++++++++++++++++++++++++++++- docs/configure.txt | 12 ++++++++++++ 4 files changed, 50 insertions(+), 2 deletions(-) diff --git a/Makefile.am b/Makefile.am index 967332abf1..0cfc54e760 100644 --- a/Makefile.am +++ b/Makefile.am @@ -899,7 +899,8 @@ MAINTAINERCLEANFILES += config.nut_report_feature.log* # Older boundary of the ChangeLog commits range # It can be a tag ('v2.2.0'), a commit hash, a date, ... # See gitrevisions for more information on specifying ranges -GITLOG_START_POINT=v2.6.0 +#GITLOG_START_POINT=v2.6.0 +GITLOG_START_POINT=@GITLOG_START_POINT@ # Force ChangeLog regeneration upon make dist (due to nonexistant 'dummy-stamp'), # in case it has already been generated previously diff --git a/NEWS.adoc b/NEWS.adoc index d5fd6db789..3a0af3f4c8 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -245,6 +245,14 @@ https://github.com/networkupstools/nut/milestone/9 * Option to `configure --enable-docs-changelog` was added, specifically to allow developer iterations to not waste CPU time rebuilding the huge `ChangeLog*` files whenever their Git index changes. + * Option to `configure --with-docs-changelog-start` was added to allow + developers to customize the size of `ChangeLog*` files when they are + generated. Default value is `auto` which applies the legacy default + `v2.6.0` to release/pre-release builds, or when local Git version info + could not be retrieved, and the most-recent release tag (or `master` + as fallback) for usual build iterations. Balancing against the option + to not build `ChangeLog*` files at all, this one allows quicker builds + that exercise all relevant recipe code paths. - The `BUILD_TYPE=default-all-errors ci_build.sh` script handling was revised to simplify code, and to default in CI builds to a quicker diff --git a/configure.ac b/configure.ac index 3a8a466eac..cc9541febd 100644 --- a/configure.ac +++ b/configure.ac @@ -2489,6 +2489,8 @@ NUT_ARG_WITH([doc], [build and install documentation (see docs/configure.txt for NUT_ARG_ENABLE([docs-man-for-progs-built-only], [build and install man pages (if enabled) only for built programs (yes, default) or all known pages (no)], [yes]) NUT_ARG_ENABLE([docs-changelog], [(re-)generate ChangeLog* files - and do so whenever git info changes? (default: auto; yes, no, "adoc,html,pdf"...)], [auto]) +NUT_ARG_WITH([docs-changelog-start], [Starting point when generating ChangeLog* files (default: auto; otherwise Git commit ID)], [auto]) + dnl Different OS distributions have different layouts of man page section dnl numbers. The one we treat as default seems to be most wide-spread, in dnl Linux and FreeBSD. For others, there are other defaults (see `man man` @@ -4129,7 +4131,31 @@ AM_CONDITIONAL(WITH_CHANGELOG_HTML_SINGLE, test "${WITH_CHANGELOG_HTML_SINGLE}" AM_CONDITIONAL(WITH_CHANGELOG_HTML_CHUNKED, test "${WITH_CHANGELOG_HTML_CHUNKED}" = "yes") AM_CONDITIONAL(WITH_CHANGELOG_PDF, test "${WITH_CHANGELOG_PDF}" = "yes") -NUT_REPORT([Would generate ChangeLog* file formats], [text:${WITH_CHANGELOG_TEXT} adoc:${WITH_CHANGELOG_ADOC} html-single:${WITH_CHANGELOG_HTML_SINGLE} html-chunked:${WITH_CHANGELOG_HTML_CHUNKED} pdf:${WITH_CHANGELOG_PDF}]) +case "${nut_with_docs_changelog_start}" in + yes|no|skip|"") + AC_MSG_WARN([Option value --with-docs-changelog-start='${nut_with_docs_changelog_start}' is not supported, switching to 'auto']) + nut_with_docs_changelog_start=auto + ;; +esac + +case "${nut_with_docs_changelog_start}" in + auto) + AS_IF([$NUT_SOURCE_GITREV_IS_RELEASE || $NUT_SOURCE_GITREV_IS_PRERELEASE || test x"${NUT_SOURCE_GITREV_NUMERIC}" = x], + [dnl # NUT v2.6.0 is the oldest release with asciidoc rendered into PDF + GITLOG_START_POINT=v2.6.0 + ], + [dnl # Try to cut off from preceding release tag (as known in this git workspace index) + GITLOG_START_POINT=v"`echo "${NUT_SOURCE_GITREV_NUMERIC}" | sed -e 's/^\(@<:@0-9@:>@*\.@<:@0-9@:>@*\.@<:@0-9@:>@*\)@<:@^0-9@:>@*.*$/\1/'`" \ + && test x"${GITLOG_START_POINT}" != xv \ + || GITLOG_START_POINT="master" + ]) + ;; + *) dnl # Else assume this is a git hash/tag/branch... + GITLOG_START_POINT="${nut_with_docs_changelog_start}" + ;; +esac + +NUT_REPORT([would generate ChangeLog* file formats], [text:${WITH_CHANGELOG_TEXT} adoc:${WITH_CHANGELOG_ADOC} html-single:${WITH_CHANGELOG_HTML_SINGLE} html-chunked:${WITH_CHANGELOG_HTML_CHUNKED} pdf:${WITH_CHANGELOG_PDF} starting from '${GITLOG_START_POINT}']) dnl NOTE: Sections may be strings, not pure numbers, on some platforms: MAN_SECTION_API="${nut_with_docs_man_section_api}" @@ -5867,6 +5893,7 @@ AC_SUBST(OS_NAME) AC_SUBST(TREE_VERSION) AC_SUBST(NUT_NETVERSION) AC_SUBST(FORCE_NUT_VERSION) +AC_SUBST(GITLOG_START_POINT) AC_SUBST(NUT_SOURCE_GITREV) AC_SUBST(NUT_SOURCE_GITREV_IS_RELEASE) AC_SUBST(NUT_SOURCE_GITREV_IS_PRERELEASE) diff --git a/docs/configure.txt b/docs/configure.txt index 788ee92b0e..7400442283 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -400,6 +400,18 @@ optional suffixes to build (empty/'=yes'), consider ('=auto') or not-build ('=no' or '=skip') specific formats; note that some are prerequisites for others (plain 'text' and prepared 'adoc' are needed to generate HTML and PDF). + --with-docs-changelog-start= + +This option was added to allow developers (and CI build agents) to customize +the size of `ChangeLog*` files when they are generated. Balancing against the +option above to not build `ChangeLog*` files at all, this one allows quicker +builds that exercise all relevant recipe code paths. + +Default value is `auto`, which applies the legacy default `v2.6.0` either to +release/pre-release builds, or when local Git version metadata could not be +retrieved, and the most-recent release tag (or `master` as fallback) for usual +build iterations. + Python support ~~~~~~~~~~~~~~ From 6a8420d057be384737281d8b47cd893ee167e26f Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 14:04:35 +0200 Subject: [PATCH 05/13] docs/docinfo.xml.sh.in: make it a template for configure script to generate and embed a @GITLOG_START_POINT@ value to consider Signed-off-by: Jim Klimov --- configure.ac | 1 + docs/.gitignore | 1 + docs/Makefile.am | 2 +- docs/configure.txt | 4 ++++ docs/{docinfo.xml.sh => docinfo.xml.sh.in} | 6 +++++- 5 files changed, 12 insertions(+), 2 deletions(-) rename docs/{docinfo.xml.sh => docinfo.xml.sh.in} (96%) diff --git a/configure.ac b/configure.ac index cc9541febd..8b62f18621 100644 --- a/configure.ac +++ b/configure.ac @@ -6701,6 +6701,7 @@ AC_CONFIG_FILES([ AC_MSG_NOTICE([Generating templated script files that should be marked executable]) m4_foreach_w([SCRIPTFILE], [ + docs/docinfo.xml.sh lib/libupsclient-config scripts/Aix/nut.init scripts/HP-UX/postinstall diff --git a/docs/.gitignore b/docs/.gitignore index f01b9bddd3..91841d913d 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -14,6 +14,7 @@ /qa-guide.xml /solaris-usb.xml /cables.xml +/docinfo.xml.sh /docinfo.xml /docinfo-since-v*.xml* /*-docinfo.xml* diff --git a/docs/Makefile.am b/docs/Makefile.am index 5e511a29a1..89b922d644 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -415,7 +415,7 @@ man: +@if [ x"$(DOCS_NO_MAN)" = xtrue ] ; then echo " DOC-NOT-MAN SKIP: $@ called in docs/Makefile" ; exit 0 ; fi ; \ cd $(abs_top_builddir)/docs/man/ && $(MAKE) $(AM_MAKEFLAGS) -f Makefile all -CLEANFILES = *.xml *.html *.pdf *-spellchecked* *-contentchecked* .check-* docbook-xsl.css docinfo.xml.in.tmp docinfo-since-v*.xml* *-docinfo.xml* +CLEANFILES = *.xml *.html *.pdf *-spellchecked* *-contentchecked* .check-* docbook-xsl.css docinfo.xml.in.tmp docinfo-since-v*.xml* *-docinfo.xml* docinfo.xml.sh CLEANFILES += $(top_builddir)/INSTALL.nut $(top_builddir)/UPGRADING $(top_builddir)/ChangeLog.adoc CLEANFILES += $(top_builddir)/*.adoc-parsed *.adoc-parsed # These two "must be" there per autotools standards, so a "make clean" diff --git a/docs/configure.txt b/docs/configure.txt index 7400442283..48a4a3ce5d 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -412,6 +412,10 @@ release/pre-release builds, or when local Git version metadata could not be retrieved, and the most-recent release tag (or `master` as fallback) for usual build iterations. +NOTE: The resulting `GITLOG_START_POINT` value may also impact the oldest +version considered by maintainer helper script `docs/docinfo.xml.sh` (if it +specifies a `v*` tag, otherwise `v2.6.0` is used). + Python support ~~~~~~~~~~~~~~ diff --git a/docs/docinfo.xml.sh b/docs/docinfo.xml.sh.in similarity index 96% rename from docs/docinfo.xml.sh rename to docs/docinfo.xml.sh.in index 96fe059239..56f4c6c681 100755 --- a/docs/docinfo.xml.sh +++ b/docs/docinfo.xml.sh.in @@ -17,7 +17,11 @@ SCRIPTDIR="`dirname "$0"`" \ [ -n "${DOCINFO_XML-}" ] || DOCINFO_XML="${SCRIPTDIR}/docinfo.xml.in" # NUT v2.6.0 is the oldest release with asciidoc rendered into PDF -[ -n "${DOCINFO_OLDEST_TAG-}" ] || DOCINFO_OLDEST_TAG="v2.6.0" +[ -n "${DOCINFO_OLDEST_TAG-}" ] || \ +case "@GITLOG_START_POINT@" in + v*) DOCINFO_OLDEST_TAG="@GITLOG_START_POINT@" ;; + *) DOCINFO_OLDEST_TAG="v2.6.0" ;; +esac generate_tags() { # Find commits whose history includes DOCINFO_OLDEST_TAG From eddb2ae2466b0abb0ee232e286d6927d4f697adc Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 15:08:00 +0200 Subject: [PATCH 06/13] docs/Makefile.am: .adoc => .adoc-parsed: double-check that input file exists If a recipe iteration is written incorrectly, make can skip work on some rules (evaluating them as true without writing outputs we need) Signed-off-by: Jim Klimov --- docs/Makefile.am | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 89b922d644..7315e44f4f 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -434,7 +434,11 @@ MAINTAINER_ASCIIDOCS_CHANGELOG_DEBUG = no # the asciidoc markup (use double-hash to avoid conversion). # The $< is okay here, it is used in a suffix rule below .adoc.adoc-parsed: - @if [ -s '$@' ] && [ x"`find '$@' -newer '$<'`" != x ] ; then \ + +@if [ ! -s '$<' ] ; then \ + echo " DOC-ASCIIDOC-GITHUB-LINKS STRANGE: input $< does not exist or is empty" >&2 ; \ + $(MAKE) $(AM_MAKEFLAGS) '$<' ; \ + fi + @if [ -s '$@' ] && [ -s '$<' ] && [ x"`find '$@' -newer '$<'`" != x ] ; then \ echo " DOC-ASCIIDOC-GITHUB-LINKS SKIP: $@ already exists and is newer than $<" ; \ if [ x"$(MAINTAINER_ASCIIDOCS_CHANGELOG_DEBUG)" != xno ] ; then \ ls -lad $@ $< || true ; \ From f718bd0f6ddc3dba1245f23e6caef01ff148f30e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 15:09:43 +0200 Subject: [PATCH 07/13] docs/Makefile.am: when writing temporary outputs, make sure they are not empty before moving to final name (else delete and bail out) Signed-off-by: Jim Klimov --- docs/Makefile.am | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 7315e44f4f..a13f38d82d 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -462,7 +462,9 @@ MAINTAINER_ASCIIDOCS_CHANGELOG_DEBUG = no -e 's%\#\(\#[1-9][0-9]*\)%\1%g' \ -e 's,\(https*://[^ \+]*\)[\]*[+],\1%2B,g' \ ; } > "$@.tmp.$$$$" \ - && mv -f "$@.tmp.$$$$" "$@" + && test -s "$@.tmp.$$$$" \ + && mv -f "$@.tmp.$$$$" "$@" \ + || { RES="$$?" ; rm -f "$@.tmp.$$$$" ; exit $$RES ; } @if [ x'$@' = x'$(top_builddir)/ChangeLog.adoc-parsed' ] ; then \ touch -r '$@' '$(top_builddir)/docs/.ChangeLog.adoc-parsed.latest' || touch '$(top_builddir)/docs/.ChangeLog.adoc-parsed.latest' ; \ fi @@ -536,8 +538,12 @@ $(top_builddir)/ChangeLog.adoc: $(top_builddir)/ChangeLog -e 's,\[\[\([^]]*\)\]\],[\1],g' \ -e 's,^\(\s\s*\)\([0-9]\),\1{empty}\2,g' \ < "$${INPUT}" >> "$@.tmp.$$$$" \ - && if [ x"`find '$@' -newer "$${INPUT}" 2>/dev/null`" != x ] ; then echo " DOC-CHANGELOG-ASCIIDOC $${INPUT} => $@ : SKIP (keep recently born competitor)"; rm -f "$@.tmp.$$$$"; \ - else mv -f "$@.tmp.$$$$" "$@" ; fi + && if [ x"`find '$@' -newer "$${INPUT}" 2>/dev/null`" != x ] ; then \ + echo " DOC-CHANGELOG-ASCIIDOC $${INPUT} => $@ : SKIP (keep recently born competitor)"; rm -f "$@.tmp.$$$$"; \ + else \ + test -s "$@.tmp.$$$$" && mv -f "$@.tmp.$$$$" "$@" \ + || { RES="$$?" ; rm -f "$@.tmp.$$$$" ; exit $$RES ; } ; \ + fi # Add other directory deps (not for local EXTRA_DIST) and generated contents FULL_USER_MANUAL_DEPS = $(USER_MANUAL_DEPS) $(SHARED_DEPS) \ @@ -1116,8 +1122,9 @@ $(NUT_SPELL_DICT).usage-report: $(NUT_SPELL_DICT) fi; \ ); \ done > "$@.tmp.$$$$" \ - && test -f "$@.tmp.$$$$" \ - && mv -f "$@.tmp.$$$$" "$@" + && test -s "$@.tmp.$$$$" \ + && mv -f "$@.tmp.$$$$" "$@" \ + || { RES="$$?" ; rm -f "$@.tmp.$$$$" ; exit $$RES ; } @echo "Reporting words from $? possibly not used in current inspected code base revision under $(abs_top_srcdir)" >&2 ; \ grep -E '^--- ' < "$@" | grep '(0 ' || echo "SUCCESS: None found" From ce9d9358093e7a744d8662a57aa34ec5c0c7ec52 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 15:10:20 +0200 Subject: [PATCH 08/13] docs/Makefile.am: ChangeLog => ChangeLog.adoc: revise definition of INPUT Actually saw it with two tokens recently, for the text and .prep-src-docs touch-file Signed-off-by: Jim Klimov --- docs/Makefile.am | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index a13f38d82d..c39906fc4f 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -504,8 +504,9 @@ MAINTAINER_ASCIIDOCS_CHANGELOG_DELAY = 10 # already running and bail out early if the file exists. Otherwise we bite # the bullet and spend a few seconds, and then re-check if another thread # did exist and finished first. +# FIXME: Fallback URL should refer not to "master" but current commit/tag? $(top_builddir)/ChangeLog.adoc: $(top_builddir)/ChangeLog - @INPUT="$?"; \ + @INPUT="$<"; \ test -n "$${INPUT}" || INPUT="$$(top_builddir)/ChangeLog" ; \ test -n "$${INPUT}" && test -n "$@" && test -s "$${INPUT}" \ || { \ From 68b4d7f2fb0c299f6831dbc765345483974b16e3 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 15:15:48 +0200 Subject: [PATCH 09/13] tools/gitlog2changelog.py.in: typo in comment Signed-off-by: Jim Klimov --- tools/gitlog2changelog.py.in | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/gitlog2changelog.py.in b/tools/gitlog2changelog.py.in index 9e88d3184b..963ae89a63 100755 --- a/tools/gitlog2changelog.py.in +++ b/tools/gitlog2changelog.py.in @@ -36,7 +36,7 @@ if len(sys.argv) > 1: # Execute git log with the desired command line options. # Support Python2 and Python3 (esp. 3.6 and earlier) semantics -# with regard to utf-8 content support (avois ascii decoding in Py3) +# with regard to utf-8 content support (avoids ascii decoding in Py3) fin_mode = 0 # Remove trailing end of line? spitlines() in py3 variant takes care of them fin_chop = 0 From c19bcec590ea8d90b687cdbc0587d38abef7ff29 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 16:28:59 +0200 Subject: [PATCH 10/13] tools/gitlog2changelog.py.in: allow specifying end of commit range, report it in text Technically a step to multi-section changelogs, covering each release separately as a range between git tags, regardless of timestamp overlap (with much older prepared commits going into much newer release later on). Signed-off-by: Jim Klimov --- tools/gitlog2changelog.py.in | 112 ++++++++++++++++++++++++++++++++++- 1 file changed, 110 insertions(+), 2 deletions(-) diff --git a/tools/gitlog2changelog.py.in b/tools/gitlog2changelog.py.in index 963ae89a63..67c9c0a169 100755 --- a/tools/gitlog2changelog.py.in +++ b/tools/gitlog2changelog.py.in @@ -28,11 +28,17 @@ try: except: pass -rev_range = "HEAD" +if len(sys.argv) > 2: + rev_range = sys.argv[2] +else: + rev_range = "HEAD" if len(sys.argv) > 1: base = sys.argv[1] - rev_range = "%s..HEAD" % base + if ".." in base: + rev_range = base + else: + rev_range = "%s..%s" % (base, rev_range) # Execute git log with the desired command line options. # Support Python2 and Python3 (esp. 3.6 and earlier) semantics @@ -72,6 +78,99 @@ except TypeError: fin_mode = 2 fin_chop = 1 +if ".." in rev_range: + rev_range_end = rev_range.split('..', 1)[1] + rev_range_start = rev_range.split('..', 1)[0] +else: + rev_range_end = rev_range + rev_range_start = None + +try: + pEnd = subprocess.Popen( + [ + "git", + "log", + "--format=%h", + "-1", + ("%s" % rev_range_end), + ], + encoding="utf-8", + close_fds=True, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) + finEnd, ferrEnd = pEnd.communicate() + if pEnd.wait() != 0: + print("ERROR getting git commit info") + sys.exit(1) + finEnd = finEnd.splitlines() + finEnd_mode = 3 +except TypeError: + finEnd = os.popen( + "git log --format=%%h -1 %s" + % rev_range_end, + "r", + ) + finEnd_mode = 2 + finEnd_chop = 1 + +rev_range_end_hash = None +for line in finEnd: + if rev_range_end_hash is None and line != "": + rev_range_end_hash = line + break + +if finEnd_mode == 3: + pEnd.stdout.close() + pEnd.stderr.close() +else: + finEnd.close() + +if rev_range_start is None: + rev_range_start_hash = None +else: + try: + pStart = subprocess.Popen( + [ + "git", + "log", + "--format=%h", + "-1", + ("%s" % rev_range_start), + ], + encoding="utf-8", + close_fds=True, + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + ) + finStart, ferrStart = pStart.communicate() + if pStart.wait() != 0: + print("ERROR getting git commit info") + sys.exit(1) + finStart = finStart.splitlines() + finStart_mode = 3 + except TypeError: + finStart = os.popen( + "git log --format=%%h -1 %s" + % rev_range_start, + "r", + ) + finStart_mode = 2 + finStart_chop = 1 + + rev_range_start_hash = None + for line in finStart: + if rev_range_start_hash is None and line != "": + rev_range_start_hash = line + break + + if finStart_mode == 3: + pStart.stdout.close() + pStart.stderr.close() + else: + finStart.close() + + # Create a ChangeLog file in the current directory by default. CHANGELOG_FILE = "ChangeLog" try: @@ -135,6 +234,15 @@ elif authorMustBeASCII_inverse_setting in ["NO", "FALSE"]: # See also: https://github.com/python/cpython/blob/main/Lib/textwrap.py wrapper = TextWrapper(initial_indent="\t", subsequent_indent="\t ", break_on_hyphens=False, break_long_words=False) +if rev_range_start is None: + rev_range_text = "NOTE: This change log section represents git commits from start of time until '%s' (commit '%s').\n\n" % (rev_range, rev_range_end_hash) +else: + rev_range_text = "NOTE: This change log section represents git commits in range '%s' (commits '%s..%s').\n\n" % (rev_range, rev_range_start_hash, rev_range_end_hash) + +fout.write(rev_range_text) +#DEBUG# sys.stderr.write(rev_range_text) +#DEBUG# sys.stderr.flush() + # The main part of the loop for line in fin: # The commit line marks the start of a new commit object. From fd24ff636b8c74373b4f8ee8f7ffc7c49d33202e Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 16:56:27 +0200 Subject: [PATCH 11/13] configure.ac, Makefile.am, docs/configure.txt, NEWS.adoc: introduce confgure option to customize git log ending point [#3019] Signed-off-by: Jim Klimov --- Makefile.am | 4 +++- NEWS.adoc | 17 ++++++++++------- configure.ac | 9 ++++++++- docs/configure.txt | 14 +++++++++----- 4 files changed, 30 insertions(+), 14 deletions(-) diff --git a/Makefile.am b/Makefile.am index 0cfc54e760..1c8ac1781e 100644 --- a/Makefile.am +++ b/Makefile.am @@ -900,7 +900,9 @@ MAINTAINERCLEANFILES += config.nut_report_feature.log* # It can be a tag ('v2.2.0'), a commit hash, a date, ... # See gitrevisions for more information on specifying ranges #GITLOG_START_POINT=v2.6.0 +#GITLOG_END_POINT=HEAD GITLOG_START_POINT=@GITLOG_START_POINT@ +GITLOG_END_POINT=@GITLOG_END_POINT@ # Force ChangeLog regeneration upon make dist (due to nonexistant 'dummy-stamp'), # in case it has already been generated previously @@ -949,7 +951,7 @@ $(abs_top_builddir)/ChangeLog: tools/gitlog2changelog.py dummy-stamp fi ; \ 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) \ + $(abs_top_builddir)/tools/gitlog2changelog.py $(GITLOG_START_POINT) $(GITLOG_END_POINT) \ && { echo " DOC-CHANGELOG-GENERATE $@ : SUCCESS"; } \ || { \ echo " DOC-CHANGELOG-GENERATE $@ : FAILED (non-fatal)" >&2 ; \ diff --git a/NEWS.adoc b/NEWS.adoc index 3a0af3f4c8..5764bc768b 100644 --- a/NEWS.adoc +++ b/NEWS.adoc @@ -244,15 +244,18 @@ https://github.com/networkupstools/nut/milestone/9 (legacy default) or for all of them (as needed for docs sites). [#2976] * Option to `configure --enable-docs-changelog` was added, specifically to allow developer iterations to not waste CPU time rebuilding the huge - `ChangeLog*` files whenever their Git index changes. - * Option to `configure --with-docs-changelog-start` was added to allow - developers to customize the size of `ChangeLog*` files when they are - generated. Default value is `auto` which applies the legacy default + `ChangeLog*` files whenever their Git index changes. [#3019] + * Options to `configure --with-docs-changelog-start` and/or + `configure --with-docs-changelog-end` were added to allow developers + to customize the size of `ChangeLog*` files when they are generated. + Default starting value is `auto` which applies the legacy default `v2.6.0` to release/pre-release builds, or when local Git version info could not be retrieved, and the most-recent release tag (or `master` - as fallback) for usual build iterations. Balancing against the option - to not build `ChangeLog*` files at all, this one allows quicker builds - that exercise all relevant recipe code paths. + as fallback) for usual build iterations. Default ending value is `HEAD` + for the current git commit at the moment the ChangeLog is (re-)generated. + Balancing against the option to not build `ChangeLog*` files at all, + this couple allows quicker builds that exercise all relevant recipe + code paths. [#3019] - The `BUILD_TYPE=default-all-errors ci_build.sh` script handling was revised to simplify code, and to default in CI builds to a quicker diff --git a/configure.ac b/configure.ac index 8b62f18621..f833af43e9 100644 --- a/configure.ac +++ b/configure.ac @@ -2490,6 +2490,7 @@ NUT_ARG_ENABLE([docs-man-for-progs-built-only], [build and install man pages (if NUT_ARG_ENABLE([docs-changelog], [(re-)generate ChangeLog* files - and do so whenever git info changes? (default: auto; yes, no, "adoc,html,pdf"...)], [auto]) NUT_ARG_WITH([docs-changelog-start], [Starting point when generating ChangeLog* files (default: auto; otherwise Git commit ID)], [auto]) +NUT_ARG_WITH([docs-changelog-end], [Ending point when generating ChangeLog* files (default: HEAD; otherwise Git commit ID)], [HEAD]) dnl Different OS distributions have different layouts of man page section dnl numbers. The one we treat as default seems to be most wide-spread, in @@ -4155,7 +4156,12 @@ case "${nut_with_docs_changelog_start}" in ;; esac -NUT_REPORT([would generate ChangeLog* file formats], [text:${WITH_CHANGELOG_TEXT} adoc:${WITH_CHANGELOG_ADOC} html-single:${WITH_CHANGELOG_HTML_SINGLE} html-chunked:${WITH_CHANGELOG_HTML_CHUNKED} pdf:${WITH_CHANGELOG_PDF} starting from '${GITLOG_START_POINT}']) +case "${nut_with_docs_changelog_end}" in + yes|no|skip|""|auto) GITLOG_END_POINT=HEAD ;; + *) GITLOG_END_POINT="${nut_with_docs_changelog_end}" ;; +esac + +NUT_REPORT([would generate ChangeLog* file formats], [text:${WITH_CHANGELOG_TEXT} adoc:${WITH_CHANGELOG_ADOC} html-single:${WITH_CHANGELOG_HTML_SINGLE} html-chunked:${WITH_CHANGELOG_HTML_CHUNKED} pdf:${WITH_CHANGELOG_PDF} starting from '${GITLOG_START_POINT}' to '${GITLOG_END_POINT}']) dnl NOTE: Sections may be strings, not pure numbers, on some platforms: MAN_SECTION_API="${nut_with_docs_man_section_api}" @@ -5894,6 +5900,7 @@ AC_SUBST(TREE_VERSION) AC_SUBST(NUT_NETVERSION) AC_SUBST(FORCE_NUT_VERSION) AC_SUBST(GITLOG_START_POINT) +AC_SUBST(GITLOG_END_POINT) AC_SUBST(NUT_SOURCE_GITREV) AC_SUBST(NUT_SOURCE_GITREV_IS_RELEASE) AC_SUBST(NUT_SOURCE_GITREV_IS_PRERELEASE) diff --git a/docs/configure.txt b/docs/configure.txt index 48a4a3ce5d..b088f4feff 100644 --- a/docs/configure.txt +++ b/docs/configure.txt @@ -401,16 +401,20 @@ optional suffixes to build (empty/'=yes'), consider ('=auto') or not-build others (plain 'text' and prepared 'adoc' are needed to generate HTML and PDF). --with-docs-changelog-start= + --with-docs-changelog-end= This option was added to allow developers (and CI build agents) to customize the size of `ChangeLog*` files when they are generated. Balancing against the -option above to not build `ChangeLog*` files at all, this one allows quicker +option above to not build `ChangeLog*` files at all, this couple allows quicker builds that exercise all relevant recipe code paths. -Default value is `auto`, which applies the legacy default `v2.6.0` either to -release/pre-release builds, or when local Git version metadata could not be -retrieved, and the most-recent release tag (or `master` as fallback) for usual -build iterations. +Default value for the starting point is `auto`, which applies the legacy +default `v2.6.0` either to release/pre-release builds, or when local Git +version metadata could not be retrieved, and the most-recent release tag +(or `master` as fallback) for usual build iterations. + +Default value for the ending point is `HEAD` to represent the current commit +at the moment the `ChangeLog` file and its derivatives are (re-)generated. NOTE: The resulting `GITLOG_START_POINT` value may also impact the oldest version considered by maintainer helper script `docs/docinfo.xml.sh` (if it From 0e6f47d760e88df94c104ad9246142f6f9ad28e9 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Tue, 15 Jul 2025 19:37:43 +0200 Subject: [PATCH 12/13] docs/Makefile.am: ChangeLog => ChangeLog.adoc: typo fix in fallback INPUT Signed-off-by: Jim Klimov --- docs/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index c39906fc4f..753562142e 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -507,7 +507,7 @@ MAINTAINER_ASCIIDOCS_CHANGELOG_DELAY = 10 # FIXME: Fallback URL should refer not to "master" but current commit/tag? $(top_builddir)/ChangeLog.adoc: $(top_builddir)/ChangeLog @INPUT="$<"; \ - test -n "$${INPUT}" || INPUT="$$(top_builddir)/ChangeLog" ; \ + test -n "$${INPUT}" || INPUT="$(top_builddir)/ChangeLog" ; \ test -n "$${INPUT}" && test -n "$@" && test -s "$${INPUT}" \ || { \ MSG="FAILED to resolve input or output filename with this make implementation, or input was not generated!"; \ From e12a4d934736950f736ce6f61764b3791e463364 Mon Sep 17 00:00:00 2001 From: Jim Klimov Date: Wed, 16 Jul 2025 14:50:01 +0200 Subject: [PATCH 13/13] docs/Makefile.am: ChangeLog => ChangeLog.adoc: avoid "$<" as this is not a suffix rule Signed-off-by: Jim Klimov --- docs/Makefile.am | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/Makefile.am b/docs/Makefile.am index 753562142e..f32d431db2 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -504,9 +504,16 @@ MAINTAINER_ASCIIDOCS_CHANGELOG_DELAY = 10 # already running and bail out early if the file exists. Otherwise we bite # the bullet and spend a few seconds, and then re-check if another thread # did exist and finished first. +# Weird ways about "INPUT": in some cases the "$?" came in empty, in others +# it has several files listed, e.g. full paths to "ChangeLog .prep-src-docs". +# The "$<" may only be used for suffix rules (and nothing forbids it from +# reporting the two changed files noted above, either). The approach below +# allows us to get a most-reasonably populated path to the original (from +# tarball or freshly generated) plain-text ChangeLog file across a lot +# of "make" implementations. # FIXME: Fallback URL should refer not to "master" but current commit/tag? $(top_builddir)/ChangeLog.adoc: $(top_builddir)/ChangeLog - @INPUT="$<"; \ + @INPUT="`for F in $? ; do case "$$F" in */ChangeLog) [ -s "$$F" ] && echo "$$F"; exit 0 ;; esac; done`"; \ test -n "$${INPUT}" || INPUT="$(top_builddir)/ChangeLog" ; \ test -n "$${INPUT}" && test -n "$@" && test -s "$${INPUT}" \ || { \