[MISC] general documentation updates (#1168)

* general doc updates * fixes * use +coc specifier * add code formatting * move franklin to past maintainers, move ross to current ones * fix text position
bids-standard · Aug 1, 2022 · 7c96954 · 7c96954
1 parent c3e67f0
commit 7c96954
Show file tree

Hide file tree

Showing 9 changed files with 100 additions and 49 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -2,22 +2,24 @@
 
 See the [CONTRIBUTING](https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md) guide. Specifically:
 
-- Please keep the title of your pull request (PR) short but informative - it will
+- Please keep the title of your Pull Request (PR) short but informative - it will
   appear in the changelog.
+- If you do **not** want a PR to appear in the changelog, it must receive the `exclude-from-changelog` label.
 - Please ensure your name is credited on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md).
   To add your name, please edit our [Contributors wiki](https://github.com/bids-standard/bids-specification/wiki/Contributors) and add your name with the type of contribution.
-  For assistance, please contact @franklin-feingold or @sappelhoff.
+  For assistance, please tag @bids-standard/maintainers.
 - Use one of the following prefixes in the title of your PR:
   - `[ENH]` - enhancement of the specification that adds a new feature or
     support for a new data type
   - `[FIX]` - fix of a typo or language clarification
   - `[INFRA]` - changes to the infrastructure automating the specification
-    release (for example building HTML docs etc.)
+    release (for example building HTML docs)
+  - `[SCHEMA]` - changes to the BIDS schema and/or related code
   - `[MISC]` - everything else including changes to the file listing
     contributors
 - If you are opening a PR to obtain early feedback, but the changes
-  are not ready to be merged (a.k.a. Work in Progress PR) please
-  use a [draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
+  are not ready to be merged (also known as a "Work in Progress" PR), please
+  use a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/).
 - After opening the PR, our continuous integration services will automatically check your contribution  for formatting errors and render a preview of the BIDS specification with your changes.
   To see the checks and preview, scroll down and click on the `show all checks` link.
   From the list, select the `Details` link of the `ci/circleci: build_docs artifact` check to see the preview of the BIDS specification.

diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -34,7 +34,10 @@ This Code of Conduct applies both within project spaces and in public spaces whe
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at ffein@stanford.edu. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `bids.maintenance+coc@gmail.com`.
+The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances.
+The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,16 +18,18 @@ Jump to the following sections:
 -   [Joining the BIDS community](#joining-the-community)
 -   [Contributing through GitHub](#contributing-through-github)
 -   [Understanding issues](#understanding-issues)
--   [Writing in markdown](#writing-in-markdown)
+-   [Writing in Markdown](#writing-in-markdown)
 -   [Using macros](#using-macros)
--   [Fixing markdown style errors](#fixing-markdown-style-errors)
+-   [Fixing Markdown style errors](#fixing-markdown-style-errors)
 -   [Using pre-commit hooks](#using-pre-commit-hooks)
 -   [Adding a figure to the specifications](#adding-a-figure-to-the-specifications)
 -   [Making a change with a pull request](#making-a-change-with-a-pull-request)
 -   [Example pull request](#example-pull-request)
 -   [Commenting on a pull request](#commenting-on-a-pull-request)
 -   [Accepting suggestion from a review](#accepting-suggestion-from-a-review)
 -   [Making a change to the BIDS-schema](#making-a-change-to-the-BIDS-schema)
+-   [How the decision to merge a pull request is made?](#how-is-the-decision-to-merge-a-pull-request-made)
+-   [How is the changelog generated?](#how-is-the-changelog-generated)
 -   [Recognizing contributions](#recognizing-contributions)
 
 ## Joining the community
@@ -121,7 +123,7 @@ The current list of labels are
     These issues highlight pieces of work or discussions
     around how we can support our members and make it easier to contribute.
 
-## Writing in markdown
+## Writing in Markdown
 
 The specification documents follow the
 [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/).
@@ -131,7 +133,7 @@ You can validate your changes against the guide using
 [standalone command line tool](https://github.com/remarkjs/remark/tree/master/packages/remark-cli)
 as well as
 [a plugin for various text editors](https://github.com/remarkjs/remark-lint#editor-integrations).
-Remark preserves consistent markdown styling across the contributions.
+Remark preserves consistent Markdown styling across the contributions.
 Please ensure before submitting a contribution that you do not have any linter errors
 in your text editor.
 
@@ -157,7 +159,7 @@ Some others need to fixed manually:
 
 #### Soft rules
 
-We follow certain "soft rules" in the way we format the specification in markdown.
+We follow certain "soft rules" in the way we format the specification in Markdown.
 
 These rules are sometimes for internal consistency in terms of styling and aesthetics,
 but several of them are also there because they help the workflow of
@@ -176,13 +178,13 @@ but if they are followed they will definitely make the lives of many people easi
 
 Don't do this:
 
-```markdown
+```Markdown
 Unprocessed MEG data MUST be stored in the native file format of the MEG instrument with which the data was collected. With the MEG specification of BIDS, we wish to promote the adoption of good practices in the management of scientific data.
 ```
 
 But do this:
 
-```markdown
+```Markdown
 Unprocessed MEG data MUST be stored in the native file format of the MEG instrument
 with which the data was collected.
 With the MEG specification of BIDS, we wish to promote the adoption of good practices
@@ -196,7 +198,7 @@ in the management of scientific data.
 
 Don't do this:
 
-```markdown
+```Markdown
 | **Key name** | **Description**                                          |
 |--------------|----------------------------------------------------------|
 | Manufacturer | Manufacturer of the equipment, for example (`Siemens`)   |
@@ -210,7 +212,7 @@ That would look like this:
 
 But do this instead:
 
-```markdown
+```Markdown
 | **Key name** | **Description**                                          |
 |--------------|----------------------------------------------------------|
 | Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) |
@@ -227,12 +229,11 @@ That would look like this:
 We use [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)
 to standardize how some aspects of the BIDS specification are rendered in HTML.
 
-<!-- TODO update link once we know we have found a final home for that doc -->
-We have dedicated documentation for [this](./macro_doc.md).
+We have dedicated documentation for this, see the [macros_doc.ms](./macros_doc.md) file.
 
-## Building the specification using mkdocs
+## Building the specification using MkDocs
 
-We are using mkdocs to render our specification.
+We are using MkDocs to render our specification.
 Please follow these instructions if you would like to build the specification locally.
 
 #### 1. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer
@@ -262,14 +263,14 @@ cd bids-specification
 
 Enter all commands below from the command line prompt located at the root of the local version of the specification.
 
-#### 3. Install mkdocs, the material theme and the required extensions
+#### 3. Install MkDocs, the Material theme and the required extensions
 
 In the following links, you can find more information about
 
-- [mkdocs](https://www.mkdocs.org/#installation) and how to install it locally,
-- [the material theme](https://squidfunk.github.io/mkdocs-material/) we use.
+- [MkDocs](https://www.mkdocs.org/#installation) and how to install it locally,
+- [the Material theme](https://squidfunk.github.io/mkdocs-material/) we use.
 
-You will also need several other mkdocs plugins, like `branchcustomization` and `macros`.
+You will also need several other MkDocs plugins, like `branchcustomization` and `macros`.
 
 To install all of this make sure you have a recent version of Python on your computer.
 The [DataLad Handbook](http://handbook.datalad.org/en/latest/intro/installation.html#python-3-all-operating-systems) provides helpful instructions for setting up Python.
@@ -295,7 +296,7 @@ Note that this will create a local directory called `env` within the bids-specif
 but that its content will not be tracked by `git` because it is listed in the `.gitignore` file.
 
 Once you have activated your isolated Python environment,
-an easy way to install the correct version of mkdocs and all the other required extensions
+an easy way to install the correct version of MkDocs and all the other required extensions
 is to use the `requirements.txt` file contained in this repository as follows:
 
 ```bash
@@ -317,7 +318,7 @@ This will allow you to see a local version of the specification.
 The local address will be `http://127.0.0.1:8000`.
 You may enter that into your browser and this will bring up the specification!
 
-## Fixing markdown style errors
+## Fixing Markdown style errors
 
 We use a linter called [Remarkjs](https://github.com/remarkjs/remark-lint) to
 ensure all of our Markdown documents are consistent and well-styled.
@@ -327,7 +328,7 @@ When GitHub Actions returns an error, use the following process to resolve the i
 
 ### 1. Install NodeJS / npm
 
-We use a markdown linter written in Javascript. To run command Javascript tools
+We use a Markdown linter written in Javascript. To run command Javascript tools
 on the command line, please [download and install](https://nodejs.org/en/download/)
 NodeJS.
 
@@ -423,7 +424,7 @@ where your image will be added. For example if you want to add a figure `figure0
 Figures can be inserted in a Markdown like this (see also
 [Markdown-Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#images)):
 
-```markdown
+```Markdown
 ![text to show if image does not load](relative_path_to_file "text to show when hovering over image")
 ```
 ### Recommendations for figures
@@ -474,16 +475,17 @@ Please detail the changes you are attempting to make.
 
 #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/)
 
-Please keep the title of your pull request short but informative - it will
-appear in the [changelog](src/CHANGES.md).
+Please keep the title of your pull request short but informative because it will
+appear in the [changelog](src/CHANGES.md) ([see below](#how-is-the-changelog-generated)).
 
 Use one of the following prefixes in the title of your pull request:
 
 -   `[ENH]` - enhancement of the specification that adds a new feature or
     support for a new data type
 -   `[FIX]` - fix of a typo or language clarification
 -   `[INFRA]` - changes to the infrastructure automating the specification
-    release (for example, building HTML docs)
+    release (for example building HTML docs)
+-   `[SCHEMA]` - changes to the BIDS schema and/or related code
 -   `[MISC]` - everything else including changes to the file listing
     contributors
 
@@ -642,6 +644,7 @@ reflected in the schema as well.
 ### 2. Ensure that changes to the schema are matched in auto-generated sections of the specification
 
 The schema is used to generate a number of elements in the specification text, including:
+
 - Filename format templates
 - Entity tables
 - Entity definitions
@@ -665,11 +668,28 @@ For more information on making general changes with a pull request, please
 review
 [Making a change with a pull request](#making-a-change-with-a-pull-request).
 
-## How the decision to merge a pull request is made?
+## How is the decision to merge a pull request made?
 
 The decision-making rules are outlined in
 [DECISION-MAKING.md](DECISION-MAKING.md).
 
+## How is the changelog generated?
+
+The changelog (see `src/CHANGES.md`) is generated automatically using
+[github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator).
+You can see the workflow in the CircleCI configuration file (`.circleci/config.yml`).
+
+As it stands, the changelog is generated whenever a pull request is integrated into
+the `master` branch of the specification via a "Merge commit"
+(as opposed to "Squash and merge" or "Rebase and merge";
+see the [GitHub help page](https://help.github.com/en/articles/about-merge-methods-on-github)
+for more information on merge methods).
+
+Note that for pull requests starting with `REL:`, no changelog is generated.
+
+To exclude pull requests from showing up in the changelog, they have to be labeled with
+the "exclude-from-changelog" label.
+
 ## Recognizing contributions
 
 BIDS follows the

diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md
@@ -30,15 +30,15 @@ BIDS governance.
 
 ### Maintainers Group
 
-| Name                                                                           | Time commitment | Scope                      |
-|--------------------------------------------------------------------------------|-----------------|----------------------------|
-| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff))                | 5h/week         | Lead Maintainer            |
-| Chris Markiewicz ([@effigies](https://github.com/effigies))                    | 5h/week         |                            |
-| Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) | 5h/week         | Community development      |
-| Taylor Salo ([@tsalo](https://github.com/tsalo))                               | 3h/week         | MRI                        |
-| Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau))                            | 3h/week         | Community development, MRI |
-| Anthony Galassi  ([@bendhouseart](https://github.com/bendhouseart))            | 3h/week         | PET, Community development |
-| Eric Earl ([@ericearl](https://github.com/ericearl))                           | 2h/week         |                            |
+| Name                                                                           | Time commitment | Scope                            |
+|--------------------------------------------------------------------------------|-----------------|----------------------------------|
+| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff))                | 5h/week         | Lead Maintainer                  |
+| Chris Markiewicz ([@effigies](https://github.com/effigies))                    | 5h/week         |                                  |
+| Taylor Salo ([@tsalo](https://github.com/tsalo))                               | 3h/week         | MRI                              |
+| Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau))                            | 3h/week         | Community development, MRI       |
+| Anthony Galassi  ([@bendhouseart](https://github.com/bendhouseart))            | 3h/week         | PET, Community development       |
+| Eric Earl ([@ericearl](https://github.com/ericearl))                           | 2h/week         |                                  |
+| Ross Blair ([@rwblair](https://github.com/rwblair))                            |                 | Maintainer of the bids-validator |
 
 In addition to the [BIDS Governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group)
 classification of a maintainer, maintainers may declare a limited scope of responsibility.
@@ -48,6 +48,12 @@ One or more scopes can be chosen by the maintainer and agreed upon by the Mainta
 A maintainer is primarily responsible for issues within their chosen scope(s), although
 contributions elsewhere are welcome, as well.
 
+#### Past maintainers group members
+
+| Name                                                                           |
+|--------------------------------------------------------------------------------|
+| Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) |
+
 ### BEP Leads Group
 
 Leaders of BIDS Extension Proposals are listed in the
@@ -93,7 +99,7 @@ and heavily depends on [GitHub Pull Request Review system](https://help.github.c
    others) or proposal to release a new version needs to be done via a Pull
    Request (PR) to the Repository.
 1. Anyone can open a PR (this action is not limited to Contributors).
-1. PRs adding new Contributors must also add their GitHub names to the
+1. PRs adding new Contributors may also add their GitHub names to the
    [CODEOWNERS](./CODEOWNERS) file.
 1. A PR is eligible to be merged if and only if these conditions are met:
    1. The last commit is at least 5 working days old to allow the community to
@@ -151,8 +157,3 @@ and heavily depends on [GitHub Pull Request Review system](https://help.github.c
    merged so if you think the PR needs your attention, please review it
    promptly or request more time via Request changes.
 1. Releases are triggered the same way as any other change - via a PR.
-1. PRs MUST be merged using the "Create a merge commit" option in GitHub (by using
-   the "merge pull request" option). This is necessary for our automatic
-   changelog generator to do its work reliably. See the [GitHub help page](https://help.github.com/en/articles/about-merge-methods-on-github)
-   for information on merge methods. See the changelog generator implementation
-   in our [circleci configuration file](./.circleci/config.yml).
diff --git a/Release_Guideline.md b/Release_Guideline.md
@@ -3,6 +3,7 @@
 This document captures guidelines to follow when considering a new release of the BIDS specification.
 
 ## Background
+
 BIDS has generally followed a semantic versioning (semver) approach.
 The canonical semver text can be found at https://semver.org/, and an adaptation to documents can be found at https://semverdoc.org/.
 A specification falls somewhere between these two, as documentation does not require

diff --git a/Release_Protocol.md b/Release_Protocol.md
@@ -8,6 +8,11 @@ The protocol assumes that you have a [fork](https://help.github.com/en/articles/
 of the bids-standard/bids-specification repository and have [cloned](https://help.github.com/en/articles/cloning-a-repository)
 your fork locally to a directory called `bids-specification`.
 
+NOTE: Before you start a release, you have to ensure that the automatically generated changelog is
+**up to date**. See the relevant [section in CONTRIBUTING.md](CONTRIBUTING.md#how-is-the-changelog-generated)
+for further information. In practice this means ensuring that the most recently merged pull request was
+merged into the `master` branch using the "Merge commit" option.
+
 ### 1. Fetch the latest version of the [master branch of the BIDS-specification](https://github.com/bids-standard/bids-specification/tree/master)
 
 You should have a remote, which we will call `upstream`, for the
@@ -91,6 +96,7 @@ $ git push -u upstream rel/1.2.0
 ```
 
 ### 4. Open a pull request against the master branch
+
 Important note: The pull request title **must** be named "REL: vX.Y.Z" (for example, "REL: v1.2.0").
 
 **This will open a period of discussion for 5 business days regarding if we are ready to release.**