[ENH] Allow README file extensions. (#1033)

* Fixed contributing link

* Modified README description.

Used REQUIRED for consistency with the schema.

* Added optional file extensions.

* Added line break because 'Lint yml files' check failed.

* Applied feedback to README description.

* Removed 'free-form' from README description

Co-authored-by: Yaroslav Halchenko <[email protected]>

* Removed "(unstructured text)" at "txt" in README

* Polishing README description.

Added fogotten changes propagation to src/03-modality-agnostic-files.md

Co-authored-by: Yaroslav Halchenko <[email protected]>

Author: mateuszpawlik

src/03-modality-agnostic-files.md

@@ -143,8 +143,18 @@ Example:
 
 ### `README`
 
-Every BIDS dataset SHOULD come with a free form text file (`README`) describing the dataset in more detail.
-The `README` file MUST be either in ASCII or UTF-8 encoding.
+A REQUIRED text file, `README`, SHOULD describe the dataset in more detail.
+The `README` file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions:
+`.md` ([Markdown](https://www.markdownguide.org/)),
+`.rst` ([reStructuredText](https://docutils.sourceforge.io/rst.html)),
+or `.txt`.
+A BIDS dataset MUST NOT contain more than one `README` file (with or without extension)
+at its root directory.
+BIDS does not make any recommendations with regards to the
+[Markdown flavor](https://www.markdownguide.org/extended-syntax/#lightweight-markup-languages)
+and does not validate the syntax of Markdown and reStructuredText.
+The `README` file SHOULD be structured such that its contents can be easily understood
+even if the used format is not rendered.
 A guideline for creating a good `README` file can be found in the
 [bids-starter-kit](https://github.com/bids-standard/bids-starter-kit/blob/master/templates/README).
 

src/99-appendices/14-glossary.md

@@ -4,6 +4,6 @@ This section compiles the object definitions in the schema.
 
 <!--
   This section is autogenerated based on the src/schema.  DO NOT EDIT DIRECTLY.
-  Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#updating-the-schema
+  Follow https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md#making-a-change-to-the-BIDS-schema
 -->
 {{ MACROS___make_glossary() }}

src/schema/objects/top_level_files.yaml

@@ -21,9 +21,20 @@ LICENSE:
 README:
   name: README
   description: |
-    In addition a free form text file (`README`) describing the dataset in more details SHOULD be
-    provided.
-    The `README` file MUST be either in ASCII or UTF-8 encoding.
+    A REQUIRED text file, `README`, SHOULD describe the dataset in more detail.
+    The `README` file MUST be either in ASCII or UTF-8 encoding and MAY have one of the extensions:
+    `.md` ([Markdown](https://www.markdownguide.org/)),
+    `.rst` ([reStructuredText](https://docutils.sourceforge.io/rst.html)),
+    or `.txt`.
+    A BIDS dataset MUST NOT contain more than one `README` file (with or without extension)
+    at its root directory.
+    BIDS does not make any recommendations with regards to the
+    [Markdown flavor](https://www.markdownguide.org/extended-syntax/#lightweight-markup-languages)
+    and does not validate the syntax of Markdown and reStructuredText.
+    The `README` file SHOULD be structured such that its contents can be easily understood
+    even if the used format is not rendered.
+    A guideline for creating a good `README` file can be found in the
+    [bids-starter-kit](https://github.com/bids-standard/bids-starter-kit/blob/master/templates/README).
 dataset_description:
   name: Dataset Description
   description: |

src/schema/rules/top_level_files.yaml

@@ -3,6 +3,9 @@ README:
   required: true
   extensions:
   - None
+  - .md
+  - .rst
+  - .txt
 CHANGES:
   required: true
   extensions: