Automake 1.16.4 introduced the option of keeping a NEWS.md file. Is there interest in better accommodating variations of the traditional 'noteworthy changes' format (e.g. in a NEWS.md), without needing to patch the modules maintainer-makefile, do-release-commit-and-tag, readme-release, and announce-gen (and perhaps others)?
In the simplest case, for example, I would use an ATX '#' heading in Markdown in place of an outline-mode '*' heading. I noticed that the aforementioned modules support heading variations to varying degrees in various places: - do-release-commit-and-tag, and maint.mk's release-commit and release-prep, expect 'noteworthy changes' on line 3 of NEWS. - announce-gen allows for '[major ]changes' too, on any line in any given file, but accepts no heading prefix other than '*'. - maint.mk's NEWS_hash works on any line of NEWS, but only in the standard format. - maint.mk's news-check works on any given line of NEWS. - maint.mk's syntax-check expects NEWS. I arrived at the attached patches in an initial attempt to loosen some of these requirements, and make them more internally consistent. I wasn't sure how best to parametrise announce-gen's print_news_deltas. Before pursuing this further, I was hoping to get some feedback on whether changes in this direction are welcome, and suggestions for the implementation (or maybe someone more experienced would like to implement it instead of me). WDYT? Thanks, -- Basil
>From f0926a4d38d9b73222be73b31691949bb5edb742 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" <[email protected]> Date: Tue, 11 Nov 2025 19:21:44 +0100 Subject: [PATCH 1/4] maintainer-makefile: quieter 'release' target * top/maint.mk (update-NEWS-hash): Use AM_V_GEN. (gpgv): Detect gpgv2 via 'command -v'; calling it directly results in several 'gpgv2: command not found' messages. --- ChangeLog | 7 +++++++ top/maint.mk | 5 +++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/ChangeLog b/ChangeLog index f86ce111d5..3dea56dfa2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +2025-11-11 Basil L. Contovounesios <[email protected]> + + maintainer-makefile: Quieter 'release' target. + * top/maint.mk (update-NEWS-hash): Use AM_V_GEN. + (gpgv): Detect gpgv2 via 'command -v'; calling it directly results + in several 'gpgv2: command not found' messages. + 2025-11-10 Bruno Haible <[email protected]> argp: Don't use an 'rpl_' function name prefix if not necessary. diff --git a/top/maint.mk b/top/maint.mk index 175e687479..26a770c674 100644 --- a/top/maint.mk +++ b/top/maint.mk @@ -1275,7 +1275,8 @@ sc_immutable_NEWS: # Update the hash stored above. Do this after each release and # for any corrections to old entries. update-NEWS-hash: NEWS - perl -pi -e 's/^(old_NEWS_hash[ \t]+:?=[ \t]+).*/$${1}'"$(NEWS_hash)/" \ + $(AM_V_GEN)perl -pi \ + -e 's/^(old_NEWS_hash[ \t]+:?=[ \t]+).*/$${1}'"$(NEWS_hash)/" \ $(srcdir)/cfg.mk # Ensure that we use only the standard $(VAR) notation, @@ -1531,7 +1532,7 @@ vc-diff-check: fi) bootstrap-tools ?= autoconf,automake,gnulib -gpgv = $$(gpgv2 --version >/dev/null && echo gpgv2 || echo gpgv) +gpgv = $$(command -v gpgv2 >/dev/null && echo gpgv2 || echo gpgv) # If it's not already specified, derive the GPG key ID from # the signed tag we've just applied to mark this release. gpg_key_ID ?= \ -- 2.51.0
>From 1cabd1ee0b18a72f9b46d2a5ceceae801d8f9ae4 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" <[email protected]> Date: Tue, 11 Nov 2025 19:23:39 +0100 Subject: [PATCH 2/4] do-release-commit-and-tag: accommodate alternative NEWS formats * build-aux/do-release-commit-and-tag: Introduce new options parametrizing the NEWS file name, and its noteworthy_stub location and contents. Avoid unconditional strftime in inner Perl loop. (help): Describe the new options. --- ChangeLog | 6 ++++ build-aux/do-release-commit-and-tag | 56 ++++++++++++++++++++++------- 2 files changed, 49 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index 3dea56dfa2..48618ce474 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2025-11-11 Basil L. Contovounesios <[email protected]> + do-release-commit-and-tag: Accommodate alternative NEWS formats. + * build-aux/do-release-commit-and-tag: Introduce new options + parametrizing the NEWS file name, and its noteworthy_stub location + and contents. Avoid unconditional strftime in inner Perl loop. + (help): Describe the new options. + maintainer-makefile: Quieter 'release' target. * top/maint.mk (update-NEWS-hash): Use AM_V_GEN. (gpgv): Detect gpgv2 via 'command -v'; calling it directly results diff --git a/build-aux/do-release-commit-and-tag b/build-aux/do-release-commit-and-tag index f01934c1eb..1523e5c2d3 100755 --- a/build-aux/do-release-commit-and-tag +++ b/build-aux/do-release-commit-and-tag @@ -3,7 +3,7 @@ # controlled .prev-version file, automate the procedure by which we record # the date, release-type and version string in the NEWS file. That commit # will serve to identify the release, so apply a signed tag to it as well. -VERSION=2025-06-10.02 # UTC +VERSION=2025-11-11.17 # UTC # Note: this is a bash script (could be zsh or dash) @@ -42,12 +42,22 @@ directory. Requirements: - you use git for version-control - a version-controlled .prev-version file -- a NEWS file, with line 3 identical to this: +- a NEWS file, by default with line 3 identical to this: $noteworthy_stub Options: --branch=BRANCH set release branch (default: $branch) -C, --builddir=DIR location of (configured) Makefile (default: $builddir) + + --news=FILE NEWS file name (default: $news) + --stub=STR release heading placeholder (default: + $noteworthy_stub) + --stub-version=STR release version placeholder (default: $ver_stub) + --stub-date=STR release date placeholder (default: $date_stub) + --stub-type=STR release type placeholder (default: $type_stub) + --stub-lines=RANGE sed line address range to search for heading + (default: $stub_range) + --help print this help, then exit --version print version number, then exit @@ -80,11 +90,16 @@ EOF # Constants. noteworthy='* Noteworthy changes in release' -noteworthy_stub="$noteworthy ?.? (????-??-??) [?]" # Variables. branch=$(git branch | sed -ne '/^\* /{s///;p;q;}') builddir=. +news=NEWS +ver_stub='?.?' +date_stub='(????-??-??)' +type_stub='[?]' +noteworthy_stub="$noteworthy $ver_stub $date_stub $type_stub" +stub_range=3 while test $# != 0 do @@ -102,6 +117,12 @@ do --help|--version) ${1#--};; --branch) shift; branch=$1; shift ;; -C|--builddir) shift; builddir=$1; shift ;; + --news) shift; news=$1; shift ;; + --stub) shift; noteworthy_stub=$1; shift ;; + --stub-version) shift; ver_stub=$1; shift ;; + --stub-date) shift; date_stub=$1; shift ;; + --stub-type) shift; type_stub=$1; shift ;; + --stub-lines) shift; stub_range=$1; shift ;; --*) die "unrecognized option: $1";; *) break;; esac @@ -150,22 +171,31 @@ Makefile=$builddir/Makefile pkg=$(sed -n 's/^PACKAGE = \(.*\)/\1/p' "$Makefile") \ || die "failed to determine package name from $Makefile" -# Check that line 3 of NEWS is the stub line about to be replaced. -test "$(sed -n 3p NEWS)" = "$noteworthy_stub" \ - || die "line 3 of NEWS must be exactly '$noteworthy_stub'" +# Check that stub about to be replaced is in given NEWS line range. +stub_line=$(sed -n "${stub_range}p" $news \ + | env gl_stub="$noteworthy_stub" \ + awk '$0 == ENVIRON["gl_stub"] { print NR }') +test -n "$stub_line" || die "one of line(s) $stub_range of $news" \ + "must be exactly '$noteworthy_stub'" ## --------------- ## ## Then, changes. ## ## --------------- ## # Update NEWS to have today's date, plus desired version number and $type. -perl -MPOSIX -ni -e 'my $today = strftime "%F", localtime time;' \ - -e 'my ($type, $ver) = qw('"$type $ver"');' \ - -e 'my $pfx = "'"$noteworthy"'";' \ - -e 'print $.==3 ? "$pfx $ver ($today) [$type]\n" : $_' \ - NEWS || die 'failed to update NEWS' - -printf "version %s\n\n* NEWS: Record release date.\n" "$ver" \ +env gl_ver=$ver gl_ver_stub="$ver_stub" \ + gl_type=$type gl_type_stub="$type_stub" \ + gl_date_stub="$date_stub" gl_line="$stub_line" \ + perl -MPOSIX -pi \ + -e 'if ($. == $ENV{gl_line}) {' \ + -e ' my $today = strftime "%F", localtime time;' \ + -e ' s/\Q$ENV{gl_ver_stub}/$ENV{gl_ver}/;' \ + -e ' s/\Q$ENV{gl_date_stub}/($today)/;' \ + -e ' s/\Q$ENV{gl_type_stub}/[$ENV{gl_type}]/;' \ + -e '}' \ + $news || die 'failed to update NEWS' + +printf "version %s\n\n* ${news}: Record release date.\n" "$ver" \ | git commit -F - -a || die 'git commit failed' git tag -s -m "$pkg $ver" v$ver HEAD || die 'git tag failed' -- 2.51.0
>From 445cfe3b228004dadcd6d831a41ffdc56af09d26 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" <[email protected]> Date: Tue, 11 Nov 2025 19:24:41 +0100 Subject: [PATCH 3/4] maintainer-makefile: accommodate alternative NEWS formats * top/maint.mk (gl_noteworthy_news_): Make overridable. (news-check-regexp-prev, NEWS_file, release_commit_args): New overridable variables. (NEWS_hash, sc_immutable_NEWS, update-NEWS-hash, news-check) (announcement, release-commit, emit-commit-log): Use them. (release-prep): Ditto. Search for news-check-regexp within news-check-lines-spec instead of hard-coding line 3. --- ChangeLog | 9 +++++++++ top/maint.mk | 42 ++++++++++++++++++++++++++++-------------- 2 files changed, 37 insertions(+), 14 deletions(-) diff --git a/ChangeLog b/ChangeLog index 48618ce474..37bf035863 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,14 @@ 2025-11-11 Basil L. Contovounesios <[email protected]> + maintainer-makefile: Accommodate alternative NEWS formats. + * top/maint.mk (gl_noteworthy_news_): Make overridable. + (news-check-regexp-prev, NEWS_file, release_commit_args): New + overridable variables. + (NEWS_hash, sc_immutable_NEWS, update-NEWS-hash, news-check) + (announcement, release-commit, emit-commit-log): Use them. + (release-prep): Ditto. Search for news-check-regexp within + news-check-lines-spec instead of hard-coding line 3. + do-release-commit-and-tag: Accommodate alternative NEWS formats. * build-aux/do-release-commit-and-tag: Introduce new options parametrizing the NEWS file name, and its noteworthy_stub location diff --git a/top/maint.mk b/top/maint.mk index 26a770c674..815a23a13e 100644 --- a/top/maint.mk +++ b/top/maint.mk @@ -160,6 +160,9 @@ today = # An ERE quoted for the shell, for matching a version+date line prefix. news-check-regexp ?= '^\*.* $(VERSION_REGEXP) \($(today)\)' +# Like news-check-regexp, but as an unquoted BRE for .prev-version. +news-check-regexp-prev ?= ^\*.* $(PREV_VERSION_REGEXP) ([0-9-]*) + # Prevent programs like 'sort' from considering distinct strings to be equal. # Doing it here saves us from having to set LC_ALL elsewhere in this file. export LC_ALL = C @@ -1257,9 +1260,9 @@ sc_const_long_option: halt='add "const" to the above declarations' \ $(_sc_search_regexp) +NEWS_file ?= NEWS NEWS_hash = \ - $$($(SED) -n '/^\*.* $(PREV_VERSION_REGEXP) ([0-9-]*)/,$$p' \ - $(srcdir)/NEWS \ + $$($(SED) -n '/$(news-check-regexp-prev)/,$$p' $(srcdir)/$(NEWS_file) \ | perl -0777 -pe \ 's/^Copyright.+?Free\sSoftware\sFoundation,\sInc\.\n//ms' \ | md5sum - \ @@ -1267,14 +1270,14 @@ NEWS_hash = # Ensure that we don't accidentally insert an entry into an old NEWS block. sc_immutable_NEWS: - @if test -f $(srcdir)/NEWS; then \ + @if test -f $(srcdir)/$(NEWS_file); then \ test "$(NEWS_hash)" = '$(old_NEWS_hash)' && : || \ { echo '$(ME): you have modified old NEWS' 1>&2; exit 1; }; \ fi # Update the hash stored above. Do this after each release and # for any corrections to old entries. -update-NEWS-hash: NEWS +update-NEWS-hash: $(NEWS_file) $(AM_V_GEN)perl -pi \ -e 's/^(old_NEWS_hash[ \t]+:?=[ \t]+).*/$${1}'"$(NEWS_hash)/" \ $(srcdir)/cfg.mk @@ -1301,12 +1304,12 @@ sc_makefile_at_at_check: $$($(VC_LIST_EXCEPT) | $(GREP) -E '(^|/)(Makefile\.am|[^/]+\.mk)$$') \ && { echo '$(ME): use $$(...), not @...@' 1>&2; exit 1; } || : -news-check: NEWS +news-check: $(NEWS_file) $(AM_V_GEN)if $(SED) -n $(news-check-lines-spec)p $< \ | $(GREP) -E $(news-check-regexp) >/dev/null; then \ :; \ else \ - echo 'NEWS: $$(news-check-regexp) failed to match' 1>&2; \ + echo '$<: $$(news-check-regexp) failed to match' 1>&2; \ exit 1; \ fi @@ -1567,7 +1570,7 @@ announce_gen_args ?= announcement_Cc_ ?= $(announcement_Cc_$(release-type)) announcement_mail_headers_ ?= $(announcement_mail_headers_$(release-type)) -announcement: NEWS ChangeLog $(rel-files) +announcement: $(NEWS_file) ChangeLog $(rel-files) # Not $(AM_V_GEN) since the output of this command serves as # announcement message: it would start with " GEN announcement". $(AM_V_at)$(srcdir)/$(_build-aux)/announce-gen \ @@ -1582,18 +1585,22 @@ announcement: $$(test -n "$(gpg_keyring_url)" && \ echo --gpg-keyring-url="$(gpg_keyring_url)") \ --srcdir=$(srcdir) \ - --news=$(srcdir)/NEWS \ + --news=$(srcdir)/$(NEWS_file) \ --bootstrap-tools=$(bootstrap-tools) \ "$$(case ,$(bootstrap-tools), in (*,gnulib,*) \ echo --gnulib-version=$(gnulib-version);; esac)" \ $(addprefix --url-dir=, $(url_dir_list)) \ $(announce_gen_args) +release_commit_args ?= \ + --news=$(NEWS_file) \ + --stub='$(gl_noteworthy_news_)' \ + --stub-lines='$(news-check-lines-spec)' .PHONY: release-commit release-commit: $(AM_V_GEN)cd $(srcdir) \ && $(_build-aux)/do-release-commit-and-tag \ - -C $(abs_builddir) $(RELEASE) + -C $(abs_builddir) $(release_commit_args) $(RELEASE) ## ---------------- ## ## Updating files. ## @@ -1621,7 +1628,7 @@ upload: define emit-commit-log printf '%s\n' 'maint: post-release administrivia' '' \ - '* NEWS: Add header line for next release.' \ + '* $(NEWS_file): Add header line for next release.' \ '* .prev-version: Record previous version.' \ '* cfg.mk (old_NEWS_hash): Auto-update.' endef @@ -1690,7 +1697,8 @@ release: # Override this in cfg.mk if you follow different procedures. release-prep-hook ?= release-prep -gl_noteworthy_news_ = * Noteworthy changes in release ?.? (????-??-??) [?] +# Keep consistent with news-check-regexp and news-check-regexp-prev. +gl_noteworthy_news_ ?= * Noteworthy changes in release ?.? (????-??-??) [?] .PHONY: release-prep release-prep: $(AM_V_GEN)$(MAKE) --no-print-directory -s announcement \ @@ -1701,9 +1709,15 @@ release-prep: fi $(AM_V_at)echo $(VERSION) > $(prev_version_file) $(AM_V_at)$(MAKE) update-NEWS-hash - $(AM_V_at)perl -pi \ - -e '$$. == 3 and print "$(gl_noteworthy_news_)\n\n\n"' \ - $(srcdir)/NEWS + $(AM_V_at)n=$$($(SED) -n -E \ + '$(news-check-lines-spec){/'$(news-check-regexp)'/=}' \ + $(srcdir)/$(NEWS_file)); [ -n "$$n" ] \ + && env gl_n=$$n gl_s='$(gl_noteworthy_news_)' \ + perl -pi -e '$$. == $$ENV{gl_n} ' \ + -e ' and print "$$ENV{gl_s}\n\n\n"' \ + $(srcdir)/$(NEWS_file) \ + || { printf '$(NEWS_file): %s failed to match\n' \ + '$$(news-check-regexp)' 1>&2; exit 1; } $(AM_V_at)msg=$$($(emit-commit-log)) || exit 1; \ cd $(srcdir) && $(VC) commit -m "$$msg" -a -- 2.51.0
>From 19e0f91b592a9a5a0b968419438d1f23adbf3561 Mon Sep 17 00:00:00 2001 From: "Basil L. Contovounesios" <[email protected]> Date: Tue, 11 Nov 2025 19:30:47 +0100 Subject: [PATCH 4/4] readme-release: accommodate alternative NEWS formats * top/README-release: Generalize 'noteworthy changes' location. --- ChangeLog | 3 +++ top/README-release | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/ChangeLog b/ChangeLog index 37bf035863..f33b24356b 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,8 @@ 2025-11-11 Basil L. Contovounesios <[email protected]> + readme-release: Accommodate alternative NEWS formats. + * top/README-release: Generalize 'noteworthy changes' location. + maintainer-makefile: Accommodate alternative NEWS formats. * top/maint.mk (gl_noteworthy_news_): Make overridable. (news-check-regexp-prev, NEWS_file, release_commit_args): New diff --git a/top/README-release b/top/README-release index 0861adf1c1..5a8e8a59c1 100644 --- a/top/README-release +++ b/top/README-release @@ -28,7 +28,7 @@ Here are most of the steps we (maintainers) follow when making a release. c=check ve=check-very-expensive; git grep -q "^$ve:\$" && c=$ve make $c syntax-check distcheck -* To (i) set the date, version number, and release TYPE on line 3 of +* To (i) set the date, version number, and release TYPE near the top of NEWS, (ii) commit that, and (iii) tag the release, run # "TYPE" must be stable, beta or alpha -- 2.51.0
