Currently https://www.debian.org/doc/debian-policy/ch-source.html#source-package-handling-debian-readme-source
talks about `README.source`.

I suggest we would allow this file to alternatively be in Markdown
format, and spell the filename as `README.source(.md)`.

The suffix is relevant as many tools recognize the file as Markdown
based on the suffix and will only render it correctly with the suffix.
I am proposing Markdown specifically as it has become an industry
standard for ASCII markup and use on README.md files is very common.

Are there tools that automatically locate README.source and would need to be adapted to
find README.source.md instead ?

Cheers,

Hello,

To be clear, it is definitely already allowed to be in markdown format.
So what we would be adding would simply be an alternative file name.

As README.source is primarily for human consumption, it seems like this
wouldn't cause too much breakage.

On the other hand, is there much benefit?  People used to typing
'less debian/README.source' would need to retrain their fingers.

You can already add Vim and Emacs annotations to specify that the file
should have Markdown syntax highlighting, within the file.

This is my concern too:
the whole point of this policy is to specify the filename.

Beside this file is only useful in limited circumstances which are less
and less frequent due to improvement to dpkg and uupdate. It is unclear
why anyone would need markdown for it.

Cheers,

I guess Otto was thinkig about Gitlab/salsa which renders markdown
automatically.


Cheers,
gregor

Hi!
maintainers to learn about the source package. Most likely it is
accessed by typing $EDITOR debian/README.s<tab> and whatever follows
will be autocompleted. Having the actual suffix is important for the
file to be rendered consistently by all editors and viewers.

Examples of existing use:
https://salsa.debian.org/debian/entr/-/blob/debian/latest/debian/README.source.md
https://salsa.debian.org/js-team/jquery/-/blob/debian/3.0.0_alpha1+dfsg-2/debian/README.source.md
https://salsa.debian.org/xen-team/debian-xen/-/blob/debian/4.11.1_pre+1.733450b39b-1_exp1/debian/README.source.md
https://salsa.debian.org/samba-team/samba/-/blob/master/debian/README.source.md

In the case of the Samba package
https://salsa.debian.org/samba-team/samba/-/blob/master/debian/README.source
is a symlink to the Markdown file.

Markdown is widely used for README in the Free and Open Source
Software ecosystems, see e.g.
https://github.com/git/git/blob/master/README.md and
https://github.com/openssh/openssh-portable/blob/master/README.md.
They are used specifically with the .md suffix and not via emacs/vim
configs.

I don't think the policy needs to say anything about symlinks or
anymore about the contents than what it is already saying. My
suggestion is simply to mention the .md file type so people know they
are allowed to use it, and potentially people planning some
scanning/automation will note to look for debian/README.source*
instead of just a single plain-text file.

Thanks!

file ending with ``.md`` gets opened in Okular, which renders Markdown.

Like wise with both Bat (rust) and Glow (go), the most popular
command-line "colorized" viewers: only files ending with .md will be
correctly rendered as Markdown.

As this README.source file is intended for humans to read, and using
Markdown in READMEs is popular, I only see benefits (for humans) in
allowing Markdown in this file, and can't really think of any
downsides as autocomplete will find this file with any suffix easily
as long as nobody accidentally go and add two READMEs, which is
unlikely.