Skip to content

Commit d4678ac

Browse files
jimklimovjimklimov
authored
Merge pull request #3019 from jimklimov/issue-3019
Extend gitlog2changelog to report start/end commits and allow to tweak them; allow to disable generation of changelog formats or completely
2 parents 1c1ce36 + e12a4d9 commit d4678ac

File tree

11 files changed

+412
-25
lines changed

11 files changed

+412
-25
lines changed

‎Makefile.am‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -899,7 +899,10 @@ MAINTAINERCLEANFILES += config.nut_report_feature.log*
899899
# Older boundary of the ChangeLog commits range
900900
# It can be a tag ('v2.2.0'), a commit hash, a date, ...
901901
# See gitrevisions for more information on specifying ranges
902-
GITLOG_START_POINT=v2.6.0
902+
#GITLOG_START_POINT=v2.6.0
903+
#GITLOG_END_POINT=HEAD
904+
GITLOG_START_POINT=@GITLOG_START_POINT@
905+
GITLOG_END_POINT=@GITLOG_END_POINT@
903906

904907
# Force ChangeLog regeneration upon make dist (due to nonexistant 'dummy-stamp'),
905908
# in case it has already been generated previously
@@ -948,7 +951,7 @@ $(abs_top_builddir)/ChangeLog: tools/gitlog2changelog.py dummy-stamp
948951
fi ; \
949952
CHANGELOG_FILE="$@" $(WITH_PDF_NONASCII_TITLES_ENVVAR) \
950953
CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR="$(CHANGELOG_REQUIRE_GROUP_BY_DATE_AUTHOR_ENVVAR)" \
951-
$(abs_top_builddir)/tools/gitlog2changelog.py $(GITLOG_START_POINT) \
954+
$(abs_top_builddir)/tools/gitlog2changelog.py $(GITLOG_START_POINT) $(GITLOG_END_POINT) \
952955
&& { echo " DOC-CHANGELOG-GENERATE $@ : SUCCESS"; } \
953956
|| { \
954957
echo " DOC-CHANGELOG-GENERATE $@ : FAILED (non-fatal)" >&2 ; \

‎NEWS.adoc‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -242,6 +242,20 @@ https://github.com/networkupstools/nut/milestone/9
242242
* Option to `configure --enable-docs-man-for-progs-built-only` was added,
243243
to differentiate NUT builds that deliver man pages for only built programs
244244
(legacy default) or for all of them (as needed for docs sites). [#2976]
245+
* Option to `configure --enable-docs-changelog` was added, specifically
246+
to allow developer iterations to not waste CPU time rebuilding the huge
247+
`ChangeLog*` files whenever their Git index changes. [#3019]
248+
* Options to `configure --with-docs-changelog-start` and/or
249+
`configure --with-docs-changelog-end` were added to allow developers
250+
to customize the size of `ChangeLog*` files when they are generated.
251+
Default starting value is `auto` which applies the legacy default
252+
`v2.6.0` to release/pre-release builds, or when local Git version info
253+
could not be retrieved, and the most-recent release tag (or `master`
254+
as fallback) for usual build iterations. Default ending value is `HEAD`
255+
for the current git commit at the moment the ChangeLog is (re-)generated.
256+
Balancing against the option to not build `ChangeLog*` files at all,
257+
this couple allows quicker builds that exercise all relevant recipe
258+
code paths. [#3019]
245259

246260
- The `BUILD_TYPE=default-all-errors ci_build.sh` script handling was
247261
revised to simplify code, and to default in CI builds to a quicker

‎ci_build.sh‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2566,6 +2566,10 @@ bindings)
25662566
else
25672567
# Help developers debug:
25682568
CONFIG_OPTS+=("--disable-silent-rules")
2569+
2570+
# In developer iterations, avoid burning CPU every
2571+
# time our git index changes
2572+
CONFIG_OPTS+=("--enable-docs-changelog=no")
25692573
fi
25702574

25712575
if [ -z "${WITH_UNMAPPED_DATAPOINTS-}" ] ; then

‎configure.ac‎

Lines changed: 182 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ dnl # Example: NUT_SOURCE_GITREV='2.8.2.695.1-696+g0e00f0777'
5050
NUT_SOURCE_GITREV="`NUT_VERSION_QUERY=DESC50 "${srcdir}/tools/gitlog2version.sh" 2>/dev/null`"
5151

5252
dnl A true/false (literally) response that can be used for prettier messages
53-
dnl emitted by NUT code.
53+
dnl emitted by NUT code, or make some "auto" configuration choices below.
5454
NUT_SOURCE_GITREV_IS_RELEASE="`NUT_VERSION_QUERY=IS_RELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`"
5555
NUT_SOURCE_GITREV_IS_PRERELEASE="`NUT_VERSION_QUERY=IS_PRERELEASE "${srcdir}/tools/gitlog2version.sh" 2>/dev/null || echo false`"
5656

@@ -2487,6 +2487,10 @@ NUT_ARG_WITH([docs], [build and install documentation (alias to --with-doc)], [m
24872487
NUT_ARG_WITH([doc], [build and install documentation (see docs/configure.txt for many variants of the option)], [${nut_with_docs}])
24882488

24892489
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])
2490+
NUT_ARG_ENABLE([docs-changelog], [(re-)generate ChangeLog* files - and do so whenever git info changes? (default: auto; yes, no, "adoc,html,pdf"...)], [auto])
2491+
2492+
NUT_ARG_WITH([docs-changelog-start], [Starting point when generating ChangeLog* files (default: auto; otherwise Git commit ID)], [auto])
2493+
NUT_ARG_WITH([docs-changelog-end], [Ending point when generating ChangeLog* files (default: HEAD; otherwise Git commit ID)], [HEAD])
24902494

24912495
dnl Different OS distributions have different layouts of man page section
24922496
dnl numbers. The one we treat as default seems to be most wide-spread, in
@@ -3985,6 +3989,180 @@ fi
39853989
AM_CONDITIONAL(WITH_PDFS, test "${WITH_PDFS}" = "yes")
39863990
AM_CONDITIONAL(SKIP_PDFS, test "${SKIP_PDFS}" = "yes")
39873991

3992+
dnl # NUT ChangeLog* files can consume a lot of build time,
3993+
dnl # so we want to let developers skip (re-)building them
3994+
dnl # if they enable docs and then iterate their code base.
3995+
WITH_CHANGELOG_TEXT=no
3996+
WITH_CHANGELOG_ADOC=no
3997+
WITH_CHANGELOG_HTML_SINGLE=no
3998+
WITH_CHANGELOG_HTML_CHUNKED=no
3999+
WITH_CHANGELOG_PDF=no
4000+
4001+
dnl # Correlate "auto" with some measure of development iterations (quick) vs. release/tarball build (full). Can maintainer-mode be it?
4002+
AS_IF([($NUT_SOURCE_GITREV_IS_RELEASE || $NUT_SOURCE_GITREV_IS_PRERELEASE) && test "${nut_enable_docs_changelog}" = auto],
4003+
[nut_enable_docs_changelog=yes]
4004+
)
4005+
4006+
case "${nut_enable_docs_changelog}" in
4007+
no|skip) AC_MSG_NOTICE([Requested to not enable WITH_CHANGELOG_*])
4008+
;;
4009+
yes)
4010+
AS_IF([test "${nut_with_doc}" != yes], [AC_MSG_ERROR([Can not enable WITH_CHANGELOG_* due to build settings or environment])])
4011+
WITH_CHANGELOG_TEXT=yes
4012+
WITH_CHANGELOG_ADOC=yes
4013+
AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no],
4014+
[WITH_CHANGELOG_HTML_SINGLE=yes],
4015+
[AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment])])
4016+
AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no],
4017+
[WITH_CHANGELOG_HTML_CHUNKED=yes],
4018+
[AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment])])
4019+
AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no],
4020+
[WITH_CHANGELOG_PDF=yes],
4021+
[AC_MSG_ERROR([Can not enable WITH_CHANGELOG_PDF due to build settings or environment])])
4022+
;;
4023+
auto|yes=auto|"")
4024+
AS_IF([test "${nut_with_doc}" = yes], [
4025+
WITH_CHANGELOG_TEXT=yes
4026+
WITH_CHANGELOG_ADOC=yes
4027+
AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no],
4028+
[WITH_CHANGELOG_HTML_SINGLE=yes],
4029+
[WITH_CHANGELOG_HTML_SINGLE=no
4030+
AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment])
4031+
])
4032+
AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no],
4033+
[WITH_CHANGELOG_HTML_CHUNKED=yes],
4034+
[WITH_CHANGELOG_HTML_CHUNKED=no
4035+
AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment])
4036+
])
4037+
AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no],
4038+
[WITH_CHANGELOG_PDF=yes],
4039+
[WITH_CHANGELOG_PDF=no
4040+
AC_MSG_WARN([Can not enable WITH_CHANGELOG_PDF due to build settings or environment])
4041+
])
4042+
], [
4043+
AC_MSG_WARN([Can not enable WITH_CHANGELOG_* due to build settings or environment])
4044+
])
4045+
;;
4046+
*)
4047+
AS_IF([test "${nut_with_doc}" = yes], [
4048+
4049+
dnl # Check each complex format desire independently:
4050+
case "${nut_enable_docs_changelog}" in
4051+
html-single=no*|*,html-single=no*|html-single=skip*|*,html-single=skip*) ;;
4052+
html-single*|*,html-single*)
4053+
AS_IF([test "${WITH_HTML_SINGLE}" = "yes" -a "${SKIP_HTML_SINGLE}" = no],
4054+
[WITH_CHANGELOG_HTML_SINGLE=yes],
4055+
[WITH_CHANGELOG_HTML_SINGLE=no
4056+
case "${nut_enable_docs_changelog}" in
4057+
*html-single=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment]) ;;
4058+
*) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_SINGLE due to build settings or environment]) ;;
4059+
esac
4060+
])
4061+
;; esac
4062+
4063+
case "${nut_enable_docs_changelog}" in
4064+
html-chunked=no*|*,html-chunked=no*|html-chunked=skip*|*,html-chunked=skip*) ;;
4065+
html-chunked*|*,html-chunked*)
4066+
AS_IF([test "${WITH_HTML_CHUNKED}" = "yes" -a "${SKIP_HTML_CHUNKED}" = no],
4067+
[WITH_CHANGELOG_HTML_CHUNKED=yes],
4068+
[WITH_CHANGELOG_HTML_CHUNKED=no
4069+
case "${nut_enable_docs_changelog}" in
4070+
*html-chunked=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment]) ;;
4071+
*) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_HTML_CHUNKED due to build settings or environment]) ;;
4072+
esac
4073+
])
4074+
;; esac
4075+
4076+
case "${nut_enable_docs_changelog}" in
4077+
pdf=no*|*,pdf=no*|pdf=skip*|*,pdf=skip*) ;;
4078+
pdf*|*,pdf*)
4079+
AS_IF([test "${WITH_PDFS}" = "yes" -a "${SKIP_PDFS}" = no],
4080+
[WITH_CHANGELOG_PDF=yes],
4081+
[WITH_CHANGELOG_PDF=no
4082+
case "${nut_enable_docs_changelog}" in
4083+
*pdf=auto*) AC_MSG_WARN([Can not enable WITH_CHANGELOG_PDF due to build settings or environment]) ;;
4084+
*) AC_MSG_ERROR([Can not enable WITH_CHANGELOG_PDF due to build settings or environment]) ;;
4085+
esac
4086+
])
4087+
;; esac
4088+
4089+
case "${nut_enable_docs_changelog}" in
4090+
adoc=no*|*,adoc=no*)
4091+
AS_IF([test "${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" != "nonono"],
4092+
[AC_MSG_ERROR([Can not disable WITH_CHANGELOG_ADOC when HTML and/or PDF build is required])])
4093+
;;
4094+
adoc=yes*|*,adoc=yes*|adoc|adoc,*|*,adoc|*,adoc,*) dnl Require enabled
4095+
WITH_CHANGELOG_ADOC=yes
4096+
;;
4097+
adoc=skip*|*,adoc=skip*|adoc=auto*|*,adoc=auto*|*)
4098+
AS_IF([test "${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" = "nonono"],
4099+
[WITH_CHANGELOG_ADOC=no],
4100+
[case "${nut_enable_docs_changelog}" in
4101+
*adoc=skip*)
4102+
AC_MSG_WARN([Can not disable WITH_CHANGELOG_ADOC when HTML and/or PDF build is required, so enabling it])
4103+
;;
4104+
esac
4105+
WITH_CHANGELOG_ADOC=yes
4106+
])
4107+
;;
4108+
esac
4109+
4110+
WITH_CHANGELOG_TEXT=yes
4111+
case "${nut_enable_docs_changelog}" in
4112+
text=no|*,text=no)
4113+
AS_IF([test "${WITH_CHANGELOG_ADOC}${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" != "nononono"],
4114+
[AC_MSG_ERROR([Can not disable WITH_CHANGELOG_TEXT when ADOC, HTML and/or PDF build is required])])
4115+
WITH_CHANGELOG_TEXT=no
4116+
;;
4117+
text=skip|*,text=skip)
4118+
AS_IF([test "${WITH_CHANGELOG_ADOC}${WITH_HTML_SINGLE}${WITH_CHANGELOG_HTML_CHUNKED}${WITH_CHANGELOG_PDF}" = "nononono"],
4119+
[WITH_CHANGELOG_TEXT=no]
4120+
[AC_MSG_WARN([Can not disable WITH_CHANGELOG_TEXT when ADOC, HTML and/or PDF build is required, so enabling it])])
4121+
;;
4122+
esac
4123+
], [
4124+
AC_MSG_WARN([Can not enable WITH_CHANGELOG_* due to build settings or environment])
4125+
])
4126+
;;
4127+
esac
4128+
4129+
AM_CONDITIONAL(WITH_CHANGELOG_TEXT, test "${WITH_CHANGELOG_TEXT}" = "yes")
4130+
AM_CONDITIONAL(WITH_CHANGELOG_ADOC, test "${WITH_CHANGELOG_ADOC}" = "yes")
4131+
AM_CONDITIONAL(WITH_CHANGELOG_HTML_SINGLE, test "${WITH_CHANGELOG_HTML_SINGLE}" = "yes")
4132+
AM_CONDITIONAL(WITH_CHANGELOG_HTML_CHUNKED, test "${WITH_CHANGELOG_HTML_CHUNKED}" = "yes")
4133+
AM_CONDITIONAL(WITH_CHANGELOG_PDF, test "${WITH_CHANGELOG_PDF}" = "yes")
4134+
4135+
case "${nut_with_docs_changelog_start}" in
4136+
yes|no|skip|"")
4137+
AC_MSG_WARN([Option value --with-docs-changelog-start='${nut_with_docs_changelog_start}' is not supported, switching to 'auto'])
4138+
nut_with_docs_changelog_start=auto
4139+
;;
4140+
esac
4141+
4142+
case "${nut_with_docs_changelog_start}" in
4143+
auto)
4144+
AS_IF([$NUT_SOURCE_GITREV_IS_RELEASE || $NUT_SOURCE_GITREV_IS_PRERELEASE || test x"${NUT_SOURCE_GITREV_NUMERIC}" = x],
4145+
[dnl # NUT v2.6.0 is the oldest release with asciidoc rendered into PDF
4146+
GITLOG_START_POINT=v2.6.0
4147+
],
4148+
[dnl # Try to cut off from preceding release tag (as known in this git workspace index)
4149+
GITLOG_START_POINT=v"`echo "${NUT_SOURCE_GITREV_NUMERIC}" | sed -e 's/^\(@<:@0-9@:>@*\.@<:@0-9@:>@*\.@<:@0-9@:>@*\)@<:@^0-9@:>@*.*$/\1/'`" \
4150+
&& test x"${GITLOG_START_POINT}" != xv \
4151+
|| GITLOG_START_POINT="master"
4152+
])
4153+
;;
4154+
*) dnl # Else assume this is a git hash/tag/branch...
4155+
GITLOG_START_POINT="${nut_with_docs_changelog_start}"
4156+
;;
4157+
esac
4158+
4159+
case "${nut_with_docs_changelog_end}" in
4160+
yes|no|skip|""|auto) GITLOG_END_POINT=HEAD ;;
4161+
*) GITLOG_END_POINT="${nut_with_docs_changelog_end}" ;;
4162+
esac
4163+
4164+
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}'])
4165+
39884166
dnl NOTE: Sections may be strings, not pure numbers, on some platforms:
39894167
MAN_SECTION_API="${nut_with_docs_man_section_api}"
39904168
MAN_SECTION_CFG="${nut_with_docs_man_section_cfg}"
@@ -5721,6 +5899,8 @@ AC_SUBST(OS_NAME)
57215899
AC_SUBST(TREE_VERSION)
57225900
AC_SUBST(NUT_NETVERSION)
57235901
AC_SUBST(FORCE_NUT_VERSION)
5902+
AC_SUBST(GITLOG_START_POINT)
5903+
AC_SUBST(GITLOG_END_POINT)
57245904
AC_SUBST(NUT_SOURCE_GITREV)
57255905
AC_SUBST(NUT_SOURCE_GITREV_IS_RELEASE)
57265906
AC_SUBST(NUT_SOURCE_GITREV_IS_PRERELEASE)
@@ -6528,6 +6708,7 @@ AC_CONFIG_FILES([
65286708

65296709
AC_MSG_NOTICE([Generating templated script files that should be marked executable])
65306710
m4_foreach_w([SCRIPTFILE], [
6711+
docs/docinfo.xml.sh
65316712
lib/libupsclient-config
65326713
scripts/Aix/nut.init
65336714
scripts/HP-UX/postinstall

‎docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
/qa-guide.xml
1515
/solaris-usb.xml
1616
/cables.xml
17+
/docinfo.xml.sh
1718
/docinfo.xml
1819
/docinfo-since-v*.xml*
1920
/*-docinfo.xml*

0 commit comments

Comments
 (0)