Simon Josefsson [2025-11-16 17:24 +0100] wrote:
> "Basil L. Contovounesios" <[email protected]> writes:
>> Simon Josefsson [2025-11-16 15:07 +0100] wrote:
>>>
>>> 3) NEWS.md -> NEWS symlink. Which format to use?
>>
>> What's the motivation/use-case for such a symlink?
>>
>> If a project insists on keeping the traditional name NEWS as the source
>> of truth, yet wants to use a different Markdown syntax, then they can
>> either override gl_noteworthy_news_ or go with case (4).
>
> Right. I don't know the use-case for this, only that if something is
> possible, someone may like that and it may become our problem if we
> break on that use-case.
That's why my initial patches were conservative and opt-in, but needed
more project-specific configuration (I didn't expect so much enthusiasm
for the feature).
Auto-detecting NEWS.md and giving it precedence over NEWS, as per the
latest patches, implies that projects will need to adapt their
configuration if they make exotic use of the NEWS and NEWS.md names.
(Does this need to be called out in Gnulib's NEWS?)
Apart from deciding on whether the default is opt-in or opt-out, and
whether NEWS or NEWS.md takes precedence, I'm not sure what else Gnulib
ought to do in this case. Do you have any suggestions?
> I just realized the GNU Standards manual demands existance of a file
> called `NEWS`. Should that be updated to say 'NEWS or NEWS.md'?
> Otherwise compatibility with the GNU standard could be motivation for
> 4).
SGTM. Shall I reply to Richard in the bug-standards subthread[0] with
something as simple as the following, or would someone else like to?
diff --git a/doc/standards.texi b/doc/standards.texi
index 05178fc507..9dddd664e4 100644
--- a/doc/standards.texi
+++ b/doc/standards.texi
@@ -3596,11 +3596,11 @@ NEWS File
@cindex @file{NEWS} file
In addition to its manual, the package should have a file named
-@file{NEWS} which contains a list of user-visible changes worth
-mentioning. In each new release, add items to the front of the file and
-identify the version they pertain to. Don't discard old items; leave
-them in the file after the newer items. This way, a user upgrading from
-any previous version can see what is new.
+@file{NEWS} (or @file{NEWS.md}) which contains a list of user-visible
+changes worth mentioning. In each new release, add items to the front
+of the file and identify the version they pertain to. Don't discard old
+items; leave them in the file after the newer items. This way, a user
+upgrading from any previous version can see what is new.
If the @file{NEWS} file gets very long, move some of the older items
into a file named @file{ONEWS} and put a note at the end referring the
[0]: https://lists.gnu.org/r/bug-standards/2025-11/msg00001.html
> Alas having both README and README.md isn't that uncommon, for example:
>
> https://github.com/openssh/openssh-portable/blob/master/README
> https://github.com/openssh/openssh-portable/blob/master/README.md
>
> I'm not a fan of this either, but there aren't exactly rules on this.
Are you in favour of proposing a similar 'or README.md' note under
(info "(standards) Releases")? There are a few references to 'README'
in maintain.texi as well, but personally I'm able to interpret those as
equally referring to a README.md file, if my project so chooses (and
whatever tooling supports it).
>> I am curious why you ask which modes we want to support, since AFAICT
>> they will all be supported once the proposed patches and appropriate
>> configuration are in place, with varying degrees of ease.
>>
>> Unless by 'support' you are referring to something broader than just the
>> README-release process?
>
> None of my comments are really about your patches now, I think -- could
> you send a final version? I think I have no issues remaining.
I don't think you've asked for any changes since the following patches:
NEWS-related: https://lists.gnu.org/r/bug-gnulib/2025-11/msg00160.html
tangential: https://lists.gnu.org/r/bug-gnulib/2025-11/msg00159.html
I attach them all below again for your convenience.
> My comments are more about how we intend things to be, and if we can or
> need to modify documentation. I think we 1) should modify GNU standards
> to say permit NEWS.md, and 2) could improve the gnulib manual to
> describe the assumptions our tooling make about handle NEWS(.md) files,
> which implicitly becomes a recommended approach.
Where do you suggest adding the latter?
- (gnulib) Miscellaneous Notes
- (gnulib) Release Management Files
- ...
I would have included it with the documentation for readme-release or
maintainer-makefile, but those are documented inline, not in the manual.
>> What is not yet supported is a generalisation from one NEWS file to an
>> arbitrary number of them, e.g. for different subsystems in the fashion
>> of Emacs' etc/{,EGLOT-,ERC-}NEWS files.
>
> I don't think we need to consider this.
Then I don't think we need to worry about parallel NEWS and NEWS.md
until someone justifies such support.
Thanks,
--
Basil
>From fee80090b33daa0442c3248b7012712b143cf36f Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email protected]>
Date: Wed, 12 Nov 2025 14:49:46 +0100
Subject: [PATCH 1/2] announce-gen: Accommodate alternative NEWS formats.
Suggested by Simon Josefsson <[email protected]> in:
<https://lists.gnu.org/r/bug-gnulib/2025-11/msg00154.html>.
* build-aux/announce-gen (print_news_deltas): Accept Markdown
ATX-style '#' headings in addition to outline-mode '*' headings.
Allow multiple repetitions of the heading marker.
---
ChangeLog | 9 +++++++++
build-aux/announce-gen | 4 ++--
2 files changed, 11 insertions(+), 2 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 8f1a59c237..e4d7e7ff05 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2025-11-15 Basil L. Contovounesios <[email protected]>
+
+ announce-gen: Accommodate alternative NEWS formats.
+ Suggested by Simon Josefsson <[email protected]> in:
+ <https://lists.gnu.org/r/bug-gnulib/2025-11/msg00154.html>.
+ * build-aux/announce-gen (print_news_deltas): Accept Markdown
+ ATX-style '#' headings in addition to outline-mode '*' headings.
+ Allow multiple repetitions of the heading marker.
+
2025-11-14 Paul Eggert <[email protected]>
openat2: fix symlink splicing bug
diff --git a/build-aux/announce-gen b/build-aux/announce-gen
index c90a33e3b2..41f298699f 100755
--- a/build-aux/announce-gen
+++ b/build-aux/announce-gen
@@ -35,7 +35,7 @@
eval 'exec perl -wSx "$0" "$@"'
if 0;
-my $VERSION = '2025-07-30 01:47'; # UTC
+my $VERSION = '2025-11-15 18:36'; # UTC
# The definition above must lie within the first 8 lines in order
# for the Emacs time-stamp write hook (at end) to update it.
# If you change this file with Emacs, please let the write hook
@@ -235,7 +235,7 @@ sub print_news_deltas ($$$)
# the first occurrence of $prev_version.
my $in_items;
- my $re_prefix = qr/(?:\* )?(?:Noteworthy c|Major c|C)(?i:hanges)/;
+ my $re_prefix = qr/(?:[#*]+ )?(?:Noteworthy c|Major c|C)(?i:hanges)/;
my $found_news;
open NEWS, '<', $news_file
--
2.51.0
>From 33be141009d072c311dd78e5e958afed08aeb844 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email protected]>
Date: Fri, 14 Nov 2025 23:42:10 +0100
Subject: [PATCH 2/2] maintainer-makefile: Auto-detect NEWS.md.
Suggested by Simon Josefsson <[email protected]> in:
<https://lists.gnu.org/r/bug-gnulib/2025-11/msg00127.html>.
* top/maint.mk (NEWS_file): Default to NEWS.md when present.
(news-check-regexp, news-check-regexp-prev): Accept headings marked
with either '#' or '*'.
(gl_noteworthy_news_): Default to a #-heading in place of
a *-heading when NEWS_file name implies Markdown.
(release-prep): Consistently prefer test over [.
---
ChangeLog | 12 ++++++++++++
top/maint.mk | 17 ++++++++++++-----
2 files changed, 24 insertions(+), 5 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index e4d7e7ff05..d554e967fe 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2025-11-15 Basil L. Contovounesios <[email protected]>
+
+ maintainer-makefile: Auto-detect NEWS.md.
+ Suggested by Simon Josefsson <[email protected]> in:
+ <https://lists.gnu.org/r/bug-gnulib/2025-11/msg00127.html>.
+ * top/maint.mk (NEWS_file): Default to NEWS.md when present.
+ (news-check-regexp, news-check-regexp-prev): Accept headings marked
+ with either '#' or '*'.
+ (gl_noteworthy_news_): Default to a #-heading in place of
+ a *-heading when NEWS_file name implies Markdown.
+ (release-prep): Consistently prefer test over [.
+
2025-11-15 Basil L. Contovounesios <[email protected]>
announce-gen: Accommodate alternative NEWS formats.
diff --git a/top/maint.mk b/top/maint.mk
index 815a23a13e..9a8dee8537 100644
--- a/top/maint.mk
+++ b/top/maint.mk
@@ -146,6 +146,12 @@ url_dir_list ?=
https://ftpmirror.gnu.org/$(PACKAGE), \
https://$(gnu_rel_host)/gnu/$(PACKAGE))
+# NEWS.md takes precedence over NEWS.
+# Override this in cfg.mk if you use a different file name.
+ifeq ($(origin NEWS_file),undefined)
+ NEWS_file := NEWS$(and $(wildcard $(srcdir)/NEWS.md),.md)
+endif
+
# An ERE matching the release date (typically today, but not necessarily).
# Override this in cfg.mk if you are using a different format in your
# NEWS file.
@@ -158,10 +164,10 @@ today =
news-check-lines-spec ?= 1,10
# An ERE quoted for the shell, for matching a version+date line prefix.
-news-check-regexp ?= '^\*.* $(VERSION_REGEXP) \($(today)\)'
+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-]*)
+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.
@@ -1260,7 +1266,6 @@ sc_const_long_option:
halt='add "const" to the above declarations' \
$(_sc_search_regexp)
-NEWS_file ?= NEWS
NEWS_hash = \
$$($(SED) -n '/$(news-check-regexp-prev)/,$$p' $(srcdir)/$(NEWS_file) \
| perl -0777 -pe \
@@ -1698,7 +1703,9 @@ release:
release-prep-hook ?= release-prep
# Keep consistent with news-check-regexp and news-check-regexp-prev.
-gl_noteworthy_news_ ?= * Noteworthy changes in release ?.? (????-??-??) [?]
+gl_noteworthy_news_ ?= \
+ $(if $(filter %.md,$(NEWS_file)),#,*) \
+ Noteworthy changes in release ?.? (????-??-??) [?]
.PHONY: release-prep
release-prep:
$(AM_V_GEN)$(MAKE) --no-print-directory -s announcement \
@@ -1711,7 +1718,7 @@ release-prep:
$(AM_V_at)$(MAKE) update-NEWS-hash
$(AM_V_at)n=$$($(SED) -n -E \
'$(news-check-lines-spec){/'$(news-check-regexp)'/=}' \
- $(srcdir)/$(NEWS_file)); [ -n "$$n" ] \
+ $(srcdir)/$(NEWS_file)); test -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"' \
--
2.51.0
>From 140ae05bf210c37ffa4651154319e7206d04dff8 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email protected]>
Date: Fri, 14 Nov 2025 19:10:11 +0100
Subject: [PATCH 1/2] announce-gen: Pacify POD errors.
* build-aux/announce-gen: Wrap all =items within =over..=back.
Terminate all C< formatting codes with >, not EOL.
(sizes): Format assignment operator like surrounding code.
(print_locations): Add missing C formatting code.
---
ChangeLog | 8 ++++++++
build-aux/announce-gen | 17 +++++++++++------
2 files changed, 19 insertions(+), 6 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 8f1a59c237..152cd15cf7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2025-11-14 Basil L. Contovounesios <[email protected]>
+
+ announce-gen: Pacify POD errors.
+ * build-aux/announce-gen: Wrap all =items within =over..=back.
+ Terminate all C< formatting codes with >, not EOL.
+ (sizes): Format assignment operator like surrounding code.
+ (print_locations): Add missing C formatting code.
+
2025-11-14 Paul Eggert <[email protected]>
openat2: fix symlink splicing bug
diff --git a/build-aux/announce-gen b/build-aux/announce-gen
index c90a33e3b2..8d02f4f5c8 100755
--- a/build-aux/announce-gen
+++ b/build-aux/announce-gen
@@ -35,7 +35,7 @@
eval 'exec perl -wSx "$0" "$@"'
if 0;
-my $VERSION = '2025-07-30 01:47'; # UTC
+my $VERSION = '2025-11-14 18:29'; # UTC
# The definition above must lie within the first 8 lines in order
# for the Emacs time-stamp write hook (at end) to update it.
# If you change this file with Emacs, please let the write hook
@@ -111,8 +111,9 @@ EOF
exit $exit_code;
}
+=over
-=item C<%size> = C<sizes (@file)>
+=item C<%size = sizes (@file)>
Compute the sizes of the C<@file> and return them as a hash. Return
C<undef> if one of the computation failed.
@@ -139,9 +140,9 @@ sub sizes (@)
return $fail ? undef : %res;
}
-=item C<print_locations ($title, \@url, \%size, @file)
+=item C<print_locations ($title, \@url, \%size, @file)>
-Print a section C<$title> dedicated to the list of <@file>, which
+Print a section C<$title> dedicated to the list of C<@file>, which
sizes are stored in C<%size>, and which are available from the C<@url>.
=cut
@@ -163,7 +164,7 @@ sub print_locations ($\@\%@)
print "\n";
}
-=item C<print_checksums (@file)
+=item C<print_checksums (@file)>
Print the SHA1 and SHA256 signature section for each C<@file>.
@@ -214,7 +215,7 @@ sub print_checksums ($@)
}
}
-=item C<print_news_deltas ($news_file, $prev_version, $curr_version)
+=item C<print_news_deltas ($news_file, $prev_version, $curr_version)>
Print the section of the NEWS file C<$news_file> addressing changes
between versions C<$prev_version> and C<$curr_version>.
@@ -720,6 +721,10 @@ EOF
exit 0;
}
+=back
+
+=cut
+
### Setup "GNU" style for perl-mode and cperl-mode.
## Local Variables:
## mode: perl
--
2.51.0
>From 508469de1da950448800d1036a54bd37a17407a9 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <[email protected]>
Date: Fri, 14 Nov 2025 23:38:38 +0100
Subject: [PATCH 2/2] maintainer-makefile: Optimize repeated executions of the
same command.
* top/maint.mk (gnulib_dir): Define as a simply (rather than
recursively) expanded variable, to avoid repeated $(shell)
invocations.
---
ChangeLog | 7 +++++++
top/maint.mk | 13 ++++++++-----
2 files changed, 15 insertions(+), 5 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 152cd15cf7..4760bf540b 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2025-11-15 Basil L. Contovounesios <[email protected]>
+
+ maintainer-makefile: Optimize repeated executions of the same command.
+ * top/maint.mk (gnulib_dir): Define as a simply (rather than
+ recursively) expanded variable, to avoid repeated $(shell)
+ invocations.
+
2025-11-14 Basil L. Contovounesios <[email protected]>
announce-gen: Pacify POD errors.
diff --git a/top/maint.mk b/top/maint.mk
index 815a23a13e..c0eda134dd 100644
--- a/top/maint.mk
+++ b/top/maint.mk
@@ -64,11 +64,14 @@ VC_LIST =
# You can override this variable in cfg.mk if your gnulib submodule lives
# in a different location.
-gnulib_dir ?= $(shell if test -n "$(GNULIB_SRCDIR)" && test -f "$(GNULIB_SRCDIR)/gnulib-tool"; then \
- echo "$(GNULIB_SRCDIR)"; \
- else \
- echo $(srcdir)/gnulib; \
- fi)
+ifeq ($(origin gnulib_dir),undefined)
+ gnulib_dir := $(shell if test -n "$(GNULIB_SRCDIR)" \
+ && test -f "$(GNULIB_SRCDIR)/gnulib-tool"; then \
+ echo "$(GNULIB_SRCDIR)"; \
+ else \
+ echo $(srcdir)/gnulib; \
+ fi)
+endif
# You can override this variable in cfg.mk to set your own regexp
# matching files to ignore.
--
2.51.0
