Allow extension for the README file

[mateuszpawlik]

GitLab, and it seems that also GitHub, cannot render markdown if the file doesn't have an extension. Currently, BIDS Validator complains that there is no README file although README.md is there. I think this is due to the following rule:

https://github.com/bids-standard/bids-specification/blob/febae4fb9b2c9f055dc1392e0283c85f05618de0/src/schema/rules/top_level_files.yaml#L2:L5

Could we change that and support file extensions for the README file? I know it would require a few changes in the documentation and maybe the validator but if we could work out the list, I'm willing to work on it.

[VisLab]

This would be a welcome addition and might encourage annotators to write a better README. Many people already use markdown for the README because OpenNeuro displays the file without the extension as markdown.

[sappelhoff]

I agree that these are good arguments to allow .md (and .txt) 👍

[sappelhoff]

This also came up before https://github.com/bids-standard/bids-validator/pull/1281#discussion_r630118909

@effigies comment from back then shows that he'd also be in favor of supporting this (with a small caveat):

I would be +1 for permitting markdown, at least. It opens up a smallish can of worms as we now get into the role of arbitrating the set of acceptable markup languages.

[mateuszpawlik]

This also came up before bids-standard/bids-validator#1281 (comment)

Thanks for finding it.

I would be +1 for permitting markdown, at least. It opens up a smallish can of worms as we now get into the role of arbitrating the set of acceptable markup languages.

I wouldn't go a far as limiting and verifying Markdown flavors. I think it is just about the file extension. As per specification, README file is a free-form text. On the other hand, the recommended README template uses Markdown already.

And if you would like to limit the Markdown flavor, I propose something standard, like CommonMark, since both GitHub and GitLab flavors are its supersets.

[sappelhoff]

We decided to deal with this after the 1.7.0 release. I think most of us agree that allowing common extensions will be fine, and we just need to decide on the subset of extensions and then implement it in the spec, examples, and validator.

I am personally in favor of permitting TXT, MD, RST - because all of these can be read reasonably well in a text document even without any rendering.

[mateuszpawlik]

I'm happy to help and I have time to commit.

[sappelhoff]

Good to hear! I think you could start to open PRs then, and we can iterate there.

[sappelhoff]

@mateuszpawlik -- just a short reminder that I think your proposal is worthwhile implementing. Let me know if you ran out of time and want me /someone else to do it instead.

[mateuszpawlik]

I'm sorry but I didn't have a long enough stretch to figure out where to start and where exactly the changes should be implemented. I still would like to do it because it's a nice, simple enough exercise to understand the ecosystem. Maybe there are some contribution details that list the things to change? If not, I'll start making a list tomorrow. Would that work?

[sappelhoff]

These are two important documents to read:

• https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md
• https://github.com/bids-standard/bids-specification/blob/master/DECISION-MAKING.md

As for making the changes, that'd be in the specification text - probably somewhere here:

• https://github.com/bids-standard/bids-specification/blob/master/src/03-modality-agnostic-files.md

For the validator, you could open an issue on https://github.com/bids-standard/bids-validator/ and we can try to see where to put the check there. I wouldn't know that off the top of my head

[mateuszpawlik]

I've started working but failed already while building #1030 .