"Basil L. Contovounesios" <[email protected]> writes: > Simon Josefsson [2025-11-16 15:07 +0100] wrote: > >> "Basil L. Contovounesios" <[email protected]> writes: >> >>> The # vs * logic isn't essential (since the variable can easily be >>> overriden), and arguably * is valid in Markdown too (where it denotes >>> a list item), but I thought # might be a saner and more semantically >>> distinct default for starting a news section. >> >> Hmm. What kind of modes do we want to support? >> >> 1) NEWS only, using '* Noteworthy...'. Just like today. >> >> 2) NEWS.md only, using '# Noteworthy...'. Seems like progress, >> but breaks backwards compatibility. > > I'm not sure I understand what the breaking change is. > > If a project has a NEWS file but later renames it to NEWS.md, then of > course that's breaking in the sense that references to the old name need > updating. > > Is that the compatibility you had in mind, or something else I'm > missing? > > If you're referring to tooling support for NEWS.md potentially not being > as complete as for NEWS, then I would consider that a missing feature > (as in this email thread) rather than a breaking change.
Both of those. I agree neither is a deal-breaker, and likely things anyone wants to get fixed anyway. But maybe sufficient for someone to not want to make that change directly. >> 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. >> 4) NEWS -> NEWS.md symlink. I think this may be what I would prefer. >> I've used README -> README.md symlinks for some time, and I haven't seen >> breakage. Would this use a different format than 3)? > > That depends on the motivation for the symlink. Case (4) looks to me > like a project that wants to avail of Markdown markup+rendering, but > wants to maintain the file's traditional name too, either for the > benefit of tooling or just consistency with older documentation. Yes. 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). >> 5) Separate NEWS and NEWS.md files. Would they duplicate content? Would >> one just say 'See the NEWS file' or 'See the NEWS.md file'? > > Again, I wonder what the motivation would be (the limits of my > imagination are clearly showing :) - personally I am a fan of > duplicating neither file names nor file contents. 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. > 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. 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. > 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. /Simon
signature.asc
Description: PGP signature
