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.
> 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).
> 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.
> 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.
---
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?
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.
Thanks,
--
Basil
