"Basil L. Contovounesios" <[email protected]> writes: > 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?
Not right now -- I think we should review and apply your patches and for interested projects attempt to make the switch to NEWS.md and see what the fall-out is. I think we'll need to continue discuss this a bit, but I don't see a show-stopper from applying patches. I experimented with the changes on a branch of libntlm using the NEWS->NEWS.md symlink approach, and it just worked, so I think I may have anticipated more trouble than actually occurs. I'm not ready (at least for some projects) to not have a NEWS file at all because that's the GNU standard and some tooling breaks without it. Maybe I can find some niche project and move to a NEWS.md only and see if there is any breakage. >> 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? Please do! Looks okay to me. >> 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). Yes I think we should acknowledge that we can use README.md for markdown-formatted version of README, and even that you don't even need a README file at all if README.md exists. The last may require tool changes. > 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. Did you assign copyright for gnulib? Sorry we should have asked this earlier to get the ball started on that. >> 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. I think either place is fine, the texinfo manual better than inline in scripts, as a starting point to get this documented. >>> 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. That would imply the recommendation is to rename NEWS to NEWS.md, doesn't it? I doubt that all projects are ready to give up the NEWS name, and I think a slow migration by using a symlink is a reasonable approach to avoid having two files with different content. So maybe that could be mentioned. /Simon
signature.asc
Description: PGP signature
