Re: How can we improve the Changes Process?

On Thu, Jul 02, 2026 at 08:05:33AM -0400, Neal Gompa wrote:

[...]

> Markdown isn't really designed for documentation. It's an ill-defined
> typesetting format meant for humans to comprehend plain text emails.

It began that way, yes.  But many open source projects use Markdown just
fine.  A quick example[1].  And as Daniel said, for 95% of the use-cases
Markdown is just fine.  

But please, let's not get our knickers in a twist about the format
itself.  Markdown, rST, AsciiDoc, or whatever, as long we settle on
_one_ open and decent enogh format that suits our needs.

> CommonMark tries to fix some of it, but it's still not great in this
> regard. 

This is somewhat true.  For deeply technical stuff, CommonMark falls
short, but it is good enough for 90% of the use-cases.

> That said, even across our services, we don't use pure
> CommonMark. Discourse, Element, Bodhi, Forgejo, and Pagure all use
> different flavors of it with different features. So even if we
> "consolidate" on Markdown, it's still going to be challenging to
> transpose without loss unless we extend all services to support the
> same Markdown features.

If I could wave a magic wand and make it happen, I'd switch to
reStructuredText (rST) + Sphinx and move on.  It is techically a
superior choice (despite some minor annoyances with syntax, but one can
live with it).  Many large upstream projects use it[2], including the
Linux kernel itself.


[1] https://github.com/reactjs/react.dev/tree/main/src/content/reference/react
[2] https://lists.fedoraproject.org/archives/list/[email protected]/message/FQS6V5LG4LYILL73OOMM26QBTAF5ELDN/

-- 
Kashyap Chamarthy / Red Hat / RISC-V and Fedora

-- 
_______________________________________________
devel mailing list -- [email protected]
To unsubscribe send an email to [email protected]
Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/
List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines
List Archives: https://lists.fedoraproject.org/archives/list/[email protected]
Do not reply to spam, report it: https://forge.fedoraproject.org/infra/tickets/issues/new