diff --git a/.circleci/artifact_path b/.circleci/artifact_path deleted file mode 100644 index c0b5dbad..00000000 --- a/.circleci/artifact_path +++ /dev/null @@ -1 +0,0 @@ -0/home/circleci/project/site/01-introduction.html diff --git a/.circleci/config.yml b/.circleci/config.yml index fbe83cb9..70f6abe9 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -2,142 +2,180 @@ version: 2 jobs: build_docs: docker: - - image: circleci/python:3.6.6 + - image: circleci/python:3.8 steps: + # checkout code to default ~/project - checkout - - run: sudo chown -R circleci:circleci /usr/local/bin - - run: sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages - - restore_cache: # ensure this step occurs *before* installing dependencies - key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }} - run: + name: install dependencies command: | - sudo pip install pip==18.0 - sudo pip install pipenv==2018.7.1 - pipenv install - - save_cache: - key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }} - paths: - - ".venv" - - "/usr/local/bin" - - "/usr/local/lib/python3.6/site-packages" + python -m pip install --upgrade pip + pip install -r requirements.txt - run: name: generate docs - command: pipenv run mkdocs build --clean --strict --verbose - - store_artifacts: - path: site + command: mkdocs build --clean --strict --verbose - persist_to_workspace: - root: . + # the mkdocs build outputs are in ~/project/site + root: ~/project paths: site linkchecker: docker: - image: yarikoptic/linkchecker:9.4.0.anchorfix1-1 steps: + # checkout code to default ~/project + - checkout - attach_workspace: - at: ~/build + # mkdocs build outputs will be in ~/project/site + at: ~/project + - run: + name: install git + command: | + apt update -y + apt install git-all -y + - run: + name: check links + command: | + git status + if (! git log -1 --pretty=oneline | grep REL:) ; then + chmod a+rX -R ~ + linkchecker -t 1 ~/project/site/ + # check external separately by pointing to all *html so no + # failures for local file:/// -- yoh found no better way, + linkchecker -t 1 --check-extern \ + --ignore-url 'file:///.*' \ + --ignore-url https://fonts.gstatic.com \ + --ignore-url "https://github.com/bids-standard/bids-specification/(pull|tree)/.*" \ + --ignore-url "https://github.com/[^/]*" \ + ~/project/site/*html ~/project/site/*/*.html + else + echo "Release PR - do nothing" + fi + + build_docs_pdf: + docker: + - image: danteev/texlive:latest + steps: + # checkout code to default ~/project + - checkout + - run: + name: install dependencies + command: | + apt-get update && apt install -y python3-pip + python3 -m pip install --upgrade pip + python3 -m pip install -r ~/project/requirements.txt + - run: + name: install font that works with unicode emojis + command: apt-get update && apt-get install -y fonts-symbola - run: + name: generate pdf version docs command: | - chmod a+rX -R ~ - linkchecker -t 1 ~/build/site/ - # check external separately by pointing to all *html so no - # failures for local file:/// -- yoh found no better way, - linkchecker -t 1 --check-extern --ignore-url 'file:///.*' --ignore-url https://fonts.gstatic.com ~/build/site/*html ~/build/site/*/*.html + cd ~/project/pdf_build_src + bash build_pdf.sh + mv ~/project/pdf_build_src/bids-spec.pdf ~/project/bids-spec.pdf + - store_artifacts: + path: bids-spec.pdf -# Auto changelog collector + # Auto changelog collector github-changelog-generator: - working_directory: ~/build docker: - image: ferrarimarco/github-changelog-generator:1.14.3 steps: - setup_remote_docker: - version: 17.11.0-ce + version: 18.06.0-ce + # checkout code to default ~/project - checkout - run: - name: Build changelog - working_directory: ~/build - command: | - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - github_changelog_generator --user bids-standard --project bids-specification --token ${CHANGE_TOKEN} --output ~/build/CHANGES.md --base ~/build/src/pregh-changes.md --header-label Changelog --no-issues --no-issues-wo-labels --no-filter-by-milestone --no-compare-link --pr-label "" - cat ~/build/CHANGES.md - mv ~/build/CHANGES.md ~/build/src/CHANGES.md - else - echo "Commit or Release, do nothing" - fi + name: Build changelog + # $CHANGE_TOKEN is generated via the GitHub web UI, and then securely stored within CircleCI web UI + command: | + mkdir ~/changelog_build + git status + if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then + github_changelog_generator \ + --user bids-standard \ + --project bids-specification \ + --token ${CHANGE_TOKEN} \ + --output ~/changelog_build/CHANGES.md \ + --base ~/project/src/pregh-changes.md \ + --header-label "# Changelog" \ + --no-issues \ + --no-issues-wo-labels \ + --no-filter-by-milestone \ + --no-compare-link \ + --pr-label "" \ + --release-branch master + cat ~/changelog_build/CHANGES.md + else + echo "Commit or Release, do nothing" + fi - persist_to_workspace: - root: . - paths: src + # raw generated changelog in ~/changelog_build/CHANGES.md + root: ~/. + paths: changelog_build -# Clear remark test + # Run remark on the auto generated changes.md file remark: - working_directory: ~ docker: - image: node:latest steps: + # checkout code to default ~/project - checkout - attach_workspace: - at: ~/build + # the freshly built CHANGES.md will be in ~/changelog_build/CHANGES.md + at: ~/. - run: - name: update-npm - command: | - cd ~ - npm install npm@latest + name: install remark and extensions + command: npm install `cat npm-requirements.txt` - run: - name: get remark - command: | - cd ~ - npm install remark remark-cli - - run: - name: get remark styles - command: | - cd ~ - npm install remark-cli@5.0.0 remark-lint@6.0.2 remark-preset-lint-recommended@3.0.2 remark-preset-lint-markdown-style-guide@2.1.2 - - run: # remark the auto generated changes.md name: remark on autogenerated CHANGES.md + # format changelog, then use sed to change * to -, then lint changelog command: | - cd ~/project - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - mkdir ~/project/src/tmp - cat ~/build/src/CHANGES.md - cp ~/build/src/CHANGES.md ~/project/src/CHANGES.md - ~/node_modules/.bin/remark ~/project/src/CHANGES.md -o ~/project/src/tmp/CHANGES.md - ~/node_modules/.bin/remark ~/project/src/tmp/CHANGES.md --frail - else - echo "Commit or Release, do nothing" - mkdir ~/project/src/tmp - touch ~/project/src/tmp/empty.txt - fi + git status + if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then + head -n 100 ~/changelog_build/CHANGES.md + npx remark-cli ~/changelog_build/CHANGES.md --rc-path ~/project/.remarkrc --output ~/changelog_build/CHANGES.md + head -n 100 ~/changelog_build/CHANGES.md + sed -i 's/* /- /' ~/changelog_build/CHANGES.md + head -n 100 ~/changelog_build/CHANGES.md + npx remark-cli ~/changelog_build/CHANGES.md --frail --rc-path ~/project/.remarkrc + else + echo "Commit or Release, do nothing" + fi - persist_to_workspace: - root: ~/project/src - paths: tmp + # fixed+linted changelog in ~/changelog_build/CHANGES.md + root: ~/. + paths: changelog_build -# Push built changelog to repo + # Push built changelog to repo Changelog-bot: - working_directory: ~/build docker: - image: circleci/openjdk:8-jdk steps: - setup_remote_docker: - version: 17.11.0-ce + version: 17.11.0-ce + # checkout code to default ~/project - checkout - attach_workspace: - at: ~/build + # fixed+linted changelog in ~/changelog_build/CHANGES.md + at: ~/. - deploy: - name: Changelog deployment - working_directory: ~/build - command: | - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - mv ~/build/tmp/CHANGES.md ~/build/src/CHANGES.md - merge_messsge=$(git log -1 | grep Merge | grep "pull") - PR_number=$(echo $merge_messsge | cut -d ' ' -f 4) - git config credential.helper 'cache --timeout=120' - git config user.email "franklin.feingold@gmail.com" - git config user.name "Changelog-bot" - git add ~/build/src/CHANGES.md - git commit -m "[DOC] Auto-generate changelog entry for PR ${PR_number}" - git push https://${CHANGE_TOKEN}@github.com/bids-standard/bids-specification.git master - else - echo "Commit or Release, do nothing" - fi + name: Changelog deployment + # $CHANGE_TOKEN is generated via the GitHub web UI, and then securely stored within CircleCI web UI + command: | + if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then + mv ~/changelog_build/CHANGES.md ~/project/src/CHANGES.md + merge_message=$(git log -1 | grep Merge | grep "pull") + PR_number=$(echo $merge_message | cut -d ' ' -f 4) + git config credential.helper 'cache --timeout=120' + git config user.email "bids.maintenance@gmail.com" + git config user.name "bids-maintenance" + git add ~/project/src/CHANGES.md + git commit -m "[DOC] Auto-generate changelog entry for PR ${PR_number}" + git push https://${CHANGE_TOKEN}@github.com/bids-standard/bids-specification.git master + else + echo "Commit or Release, do nothing" + fi workflows: version: 2 @@ -149,17 +187,26 @@ workflows: - build_docs - github-changelog-generator: filters: - branches: - only: master + branches: + only: master - remark: requires: - - github-changelog-generator + - github-changelog-generator filters: - branches: - only: master + branches: + only: master - Changelog-bot: requires: - - remark + - remark filters: - branches: - only: master + branches: + only: master + # Ensure that build_docs_pdf always runs last, so that we can use the CircleCI API link for the "latest" artifact + # https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master + - build_docs_pdf: + requires: + - build_docs + - linkchecker + - github-changelog-generator + - remark + - Changelog-bot diff --git a/.github/ISSUE_TEMPLATE/blank.md b/.github/ISSUE_TEMPLATE/blank.md new file mode 100644 index 00000000..929d0f14 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/blank.md @@ -0,0 +1,7 @@ +--- +name: Blank issue +about: Create an issue without a template. +title: '' +labels: '' +assignees: '' +--- diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..8f512bdd --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,17 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' +assignees: '' +--- + +--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE ISSUE --- + +Please ... + +- ... describe your problem in detail. +- ... describe what you expected instead of your problem. +- ... provide a link to the part of the BIDS specification that is relevant. + +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE ISSUE --- diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..a3cf9e78 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: BIDS NeuroStars forum + url: https://neurostars.org/ + about: Ask (and answer) concrete technical questions or about implementation details around BIDS. + - name: BIDS mailing list + url: https://groups.google.com/forum/#!forum/bids-discussion + about: Use the BIDS mailing list for announcements, and to draw attention to any item related to BIDS diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..b90a241a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,21 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' +assignees: '' +--- + +--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE ISSUE --- + +- Have you checked our contributing guide? It's a helpful resource: https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md + +- Is your idea backwards compatible? If not, please open an issue in the bids-2-devel repository instead of here: https://github.com/bids-standard/bids-2-devel + +- Is there already a group working on your idea? Check the BIDS extension proposals: https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification + +- Will your idea potentially require a large effort? Read BEP lead guidelines: https://docs.google.com/document/d/1pWmEEY-1-WuwBPNy5tDAxVJYQ9Een4hZJM06tQZg8X4/ + +- When you suggest your idea, please try to supply (mock) examples! + +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE ISSUE --- diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..3e3f3b6a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,25 @@ +--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST --- + +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 + appear in the changelog. +- 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. +- 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.) + - `[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/). +- 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. + +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 00000000..89d968c8 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,12 @@ +on: [status] +jobs: + circleci_artifacts_redirector_job: + runs-on: ubuntu-latest + name: Run CircleCI artifacts redirector + steps: + - name: GitHub Action step + uses: larsoner/circleci-artifacts-redirector-action@master + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + artifact-path: 0/bids-spec.pdf + circleci-jobs: build_docs_pdf diff --git a/.github/workflows/markdown_style.yml b/.github/workflows/markdown_style.yml new file mode 100644 index 00000000..578c6e8c --- /dev/null +++ b/.github/workflows/markdown_style.yml @@ -0,0 +1,17 @@ +name: Check Markdown style + +on: [push, pull_request] + +jobs: + markdown-style: + runs-on : ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Setup NodeJS + uses: actions/setup-node@v2 + with: + node-version: 14 + - name: Install dependencies + run: npm install `cat npm-requirements.txt` + - name: Run style checks + run: npx remark src/*.md src/*/*.md --frail --rc-path .remarkrc diff --git a/.github/workflows/no-bad-latin.yml b/.github/workflows/no-bad-latin.yml new file mode 100644 index 00000000..56dc8037 --- /dev/null +++ b/.github/workflows/no-bad-latin.yml @@ -0,0 +1,57 @@ + +# This action initially adopted from The Turing Way from in October 2020. +# doi:10.5281/zenodo.3233853 +# https://github.com/alan-turing-institute/the-turing-way/blob/af98c94/.github/workflows/no-bad-latin.yml +# +# This action triggers the script tools/no-bad-latin.py to and will throw an error if any latin expression (like e.g. or i.e.) is detected: +# +# This action will be triggered +# - on a push to master +# - on a PR to the master branch and will only check files that were modified in src + +name: Check for Latin Phrases + +# Decide when to run the tests +# +# This configuration sets the test to run on pushes to master +# and on pull requests that are opened to master +on: + push: + branches: + - master + pull_request: + branches: + - master + +# Set up the Continuous Integration job +jobs: + latin-phrases: + # Run on the latest Ubuntu distribution + runs-on: ubuntu-latest + # This section collects together the steps involved in running the test + steps: + # Checkout the repository. Relies on another GH-Action. + - uses: actions/checkout@v2 + # Set up the Python version. Relies on another GH-Action. + - name: Setup Python 3.7 + uses: actions/setup-python@v1 + with: + python-version: 3.7 + # Install Python dependencies + - name: Install dependencies + working-directory: ./tools + run: | + python -m pip install --upgrade pip + python -m pip install -r requirements.txt + # Run a Python script + - name: Run Python script to check for latin phrases - Master + working-directory: ./tools + if: github.event_name == 'push' && github.ref == 'refs/heads/master' + run: | + python no-bad-latin.py + + - name: Run Python script to check for latin phrases - Pull Request + working-directory: ./tools + if: github.event.pull_request + run: | + python no-bad-latin.py --pull-request ${{ github.event.pull_request.number }} diff --git a/.github/workflows/yml_lint.yml b/.github/workflows/yml_lint.yml new file mode 100644 index 00000000..9f5609af --- /dev/null +++ b/.github/workflows/yml_lint.yml @@ -0,0 +1,20 @@ +name: Lint yml files + +on: [push, pull_request] + +jobs: + yml-lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Python + uses: actions/setup-python@v1 + with: + python-version: 3.9 + - name: Install dependencies + run: pip install yamllint + - name: Lint yml files in src/schema + # for config, see: + # https://yamllint.readthedocs.io/en/stable/configuration.html#custom-configuration-without-a-config-file + run: | + yamllint -f standard src/schema/ -c .yamllint.yml diff --git a/.gitignore b/.gitignore index ccbfadbd..363a7b2c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,152 @@ -site/ \ No newline at end of file +site/ +.DS_Store +.idea +venvs + +pdf_build_src/bids-spec.pdf +pdf_build_src/src_copy + +# JS/NPM +package-lock.json +package.json +node_modules/ + +# Python gitignore +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +# For a library or package, you might want to ignore these files since the code is +# intended to run in multiple environments; otherwise, check them in: +# .python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ diff --git a/.mailmap b/.mailmap new file mode 100644 index 00000000..066e8097 --- /dev/null +++ b/.mailmap @@ -0,0 +1,66 @@ +Adam Li + +Thomas Nichols +Thomas Nichols +Thomas Nichols + +Chris Gorgolewski +Chris Gorgolewski +Chris Gorgolewski +Chris Gorgolewski + +Christopher J. Markiewicz +Christopher J. Markiewicz +Christopher J. Markiewicz + +Franklin Feingold +Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> + +Satrajit Ghosh +Satrajit Ghosh + +Remi Gau +Remi Gau <6961185+Remi-Gau@users.noreply.github.com> + +Horea Christian +Horea Christian + +Franco Pestilli +Franco Pestilli <2119795+francopestilli@users.noreply.github.com> + +Chris Holdgraf +Chris Holdgraf + +Alex Rockhill +Alex Rockhill Alex + +Cyril Pernet +Cyril Pernet + +Dora Hermes +Dora Hermes Dora + +Oscar Esteban + +bids-maintenance +bids-maintenance Changelog-bot + +Agah Karakuzu + +Wouter Potters + +Hugo Boniface + +Jose Manuel Saborit Torres + +Matt Sanderson + +Melanie Ganz + +Kay Robbins <1189050+VisLab@users.noreply.github.com> + +Patrick Park + +Ezequiel Mikulan + +Guillaume Flandin diff --git a/.prettierrc b/.prettierrc deleted file mode 100644 index 6e0d1ce8..00000000 --- a/.prettierrc +++ /dev/null @@ -1,13 +0,0 @@ -{ - "parser": "markdown", - "proseWrap": "always", - "tabWidth": 2, - "overrides": [ - { - "files": "*.md", - "options": { - "tabWidth": 4 - } - } - ] -} diff --git a/.remarkrc b/.remarkrc index 390aeb43..fc065759 100644 --- a/.remarkrc +++ b/.remarkrc @@ -1,10 +1,15 @@ { "plugins": [ "preset-lint-markdown-style-guide", + "preset-lint-recommended", + "remark-gfm", ["lint-no-duplicate-headings", false], ["lint-list-item-indent", "tab-size"], ["lint-emphasis-marker", "consistent"], ["lint-maximum-line-length", false], - ["lint-maximum-heading-length", false] + ["lint-maximum-heading-length", false], + ["lint-no-shortcut-reference-link", false], + ["lint-no-trailing-spaces"], + ["lint-no-undefined-references", false] ] } diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 69d27fe5..00000000 --- a/.travis.yml +++ /dev/null @@ -1,10 +0,0 @@ -language: node_js -node_js: - - "10" -cache: - directories: - - node_modules # NPM packages -before_script: - - npm install remark-cli@5.0.0 remark-lint@6.0.2 remark-preset-lint-recommended@3.0.2 remark-preset-lint-markdown-style-guide@2.1.2 -script: - - remark src/*.md src/*/*.md --frail diff --git a/.yamllint.yml b/.yamllint.yml new file mode 100644 index 00000000..baed8301 --- /dev/null +++ b/.yamllint.yml @@ -0,0 +1,5 @@ +extends: default + +rules: + line-length: + max: 120 diff --git a/CODEOWNERS b/CODEOWNERS index ee7729e3..5dbad3bf 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -16,5 +16,5 @@ /src/05-derivatives/03-imaging.md @effigies /src/05-derivatives/04-structural-derivatives.md @edickie @ahoopes /src/05-derivatives/05-functional-derivatives.md @effigies -/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban +/src/05-derivatives/06-diffusion-derivatives.md @francopestilli @oesteban @Lestropie /src/99-appendices/06-meg-file-formats.md @monkeyman192 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d8347167..3e347881 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,133 +1,425 @@ - # Contributing to the BIDS Specification **Welcome to the BIDS Specification repository!** -*We're so excited you're here and want to contribute.* +_We're so excited you're here and want to contribute._ -We hope that these guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know by [opening an issue](#understanding-issues). +We hope that these guidelines are designed to make it as easy as possible to get +involved. +If you have any questions that aren't discussed below, please let us know +by [opening an issue](#understanding-issues). ## Table of contents -Been here before? Already know what you're looking for in this guide? 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) -* [Make a change with a pull request](#making-a-change-with-a-pull-request) -* [Example pull request](#example-pull-request) -* [Recognizing contributions](#recognizing-contributions) +Been here before? +Already know what you're looking for in this guide? +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) +- [Fixing markdown style errors](#fixing-markdown-style-errors) +- [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) +- [Recognizing contributions](#recognizing-contributions) ## Joining the community -BIDS - the [Brain Imaging Data Structure](https://bids.neuroimaging.io/) - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. +BIDS - the [Brain Imaging Data Structure](https://bids.neuroimaging.io/) - is a +growing community of neuroimaging enthusiasts, and we want to make our resources +accessible to and engaging for as many researchers as possible. -How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! +How do you know that you're a member of the BIDS community? +You're here! +You know that BIDS exists! +You're officially a member of the community. +It's THAT easy! Welcome! -Most of our discussions take place here in [GitHub issues](#understanding-issues). -We also have a [bids-discussion](https://groups.google.com/forum/#!forum/bids-discussion) Google Group, although this is largely now an archive of previous conversations. +Most of our discussions take place here in +[GitHub issues](#understanding-issues). +We also have a +[bids-discussion](https://groups.google.com/forum/#!forum/bids-discussion) +Google Group, although this is largely now an archive of previous conversations. -Moving forward, we encourage all members to contribute here on [GitHub](https://github.com/bids-standard/bids-specification) or on the [NeuroStars](https://neurostars.org/tags/bids) Discourse Forum, under the `bids` tag. +Moving forward, we encourage all members to contribute here on +[GitHub](https://github.com/bids-standard/bids-specification) or on the +[NeuroStars](https://neurostars.org/tags/bids) Discourse Forum, under the `bids` +tag. -To keep on top of new posts, please see this guide for setting your [topic notifications](https://meta.discourse.org/t/discourse-new-user-guide/96331#heading--topic-notifications). +To keep on top of new posts, please see this guide for setting your +[topic notifications](https://meta.discourse.org/t/discourse-new-user-guide/96331#heading--topic-notifications). -As a reminder, we expect that all contributions adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). +As a reminder, we expect that all contributions adhere to our +[Code of Conduct](CODE_OF_CONDUCT.md). ## Contributing through GitHub -[Git](https://git-scm.com/) is a really useful tool for version control. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working. +[Git](https://git-scm.com/) is a really useful tool for version control. +[GitHub](https://github.com/) sits on top of git and supports collaborative and +distributed working. -We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! +We know that it can be daunting to start using git and GitHub if you haven't +worked with them in the past, but the BIDS Specification maintainers are here to +help you figure out any of the jargon or confusing instructions you encounter! -In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going. Remember that you can ask us any questions you need to along the way. +In order to contribute via GitHub you'll need to set up a free account and sign +in. +Here are some +[instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) +to help you get going. +Remember that you can ask us any questions you need to along the way. ## Understanding issues -Every project on GitHub uses [issues](https://github.com/bids-standard/bids-specification/issues) slightly differently. +Every project on GitHub uses +[issues](https://github.com/bids-standard/bids-specification/issues) slightly +differently. -The following outlines how BIDS developers think about communicating through issues. +The following outlines how BIDS developers think about communicating through +issues. -**Issues** are individual pieces of work that need to be completed or decisions that need to be made to move the project forwards. -A general guideline: if you find yourself tempted to write a great big issue that -is difficult to describe as one unit of work, please consider splitting it into two or more issues. +**Issues** are individual pieces of work that need to be completed or decisions +that need to be made to move the project forwards. +A general guideline: if you find yourself tempted to write a great big issue +that is difficult to describe as one unit of work, please consider splitting it +into two or more issues. -Issues are assigned [labels](#issue-labels) which explain how they relate to the overall project's goals and immediate next steps. +Issues are assigned [labels](#issue-labels) which explain how they relate to the +overall project's goals and immediate next steps. ### Issue labels -The current list of labels are [here](https://github.com/bids-standard/bids-specification/labels) and include: +The current list of labels are +[here](https://github.com/bids-standard/bids-specification/labels) and include: -* [![Help wanted](https://img.shields.io/badge/-help%20wanted-159818.svg)](https://github.com/bids-standard/bids-specification/labels/community) *These issues contain a task that a member of the team has determined we need additional help with.* +- [![Help wanted](https://img.shields.io/badge/-help%20wanted-159818.svg)](https://github.com/bids-standard/bids-specification/labels/help%20wanted) + _These issues contain a task that a member of the team has determined we + need additional help with._ - If you feel that you can contribute to one of these issues, we especially encourage you to do so! + If you feel that you can contribute to one of these issues, we especially + encourage you to do so! -* [![Opinions wanted](https://img.shields.io/badge/-opinions%20wanted-84b6eb.svg)](https://github.com/bids-standard/bids-specification/labels/opinions%20wanted) *These issues hold discussions where we're especially eager for feedback.* +- [![Opinions wanted](https://img.shields.io/badge/-opinions%20wanted-84b6eb.svg)](https://github.com/bids-standard/bids-specification/labels/opinions%20wanted) + _These issues hold discussions where we're especially eager for feedback._ Ongoing discussions benefit from broad feedback. - This label is used to highlight issues where decisions are being considered, so please join the conversation! + This label is used to highlight issues where decisions are being considered, + so please join the conversation! -* [![Community](https://img.shields.io/badge/-community-%23ddcc5f.svg)](https://github.com/bids-standard/bids-specification/labels/community) *These issues are related to building and supporting the BIDS community.* - - In addition to the specification itself, we are dedicated to creating a healthy community. - These issues highlight pieces of work or discussions around how we can support our members and make it easier to contribute. +- [![Community](https://img.shields.io/badge/-community-%23ddcc5f.svg)](https://github.com/bids-standard/bids-specification/labels/community) + _These issues are related to building and supporting the BIDS community._ + In addition to the specification itself, we are dedicated to creating a + healthy community. + These issues highlight pieces of work or discussions + around how we can support our members and make it easier to contribute. ## Writing in markdown -The specification documents follow the [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). +The specification documents follow the +[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). + +You can validate your changes against the guide using +[remark](https://github.com/remarkjs/remark-lint) which works as a +[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. +Please ensure before submitting a contribution that you do not have any linter errors +in your text editor. + +We have deployed a continuous integrator ([circle CI](https://circleci.com/)) to +further allow for integrating changes continuously. +The CI is testing that the changes are inline with our standard styling. + +GitHub has a helpful page on +[getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). + +### Style guide + +There are certain style rules we are trying to follow in the way the specifications are written. + +Many of those styling issues can fixed automatically using a linter: see +the section [Fixing Remark errors from Travis](#fixing-travis-remark-errors). + +Some others need to fixed manually: + +- Do not use Latin abbreviations like `"e.g"`, `"i.e"`, `"etc"` that can be confusing + to some readers and try to replace them by common English equivalents such as + `"for example"`, `"that is"`, `"and so on"`. + +#### Soft rules + +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 +tracking changes, reviewing them on GitHub, and making code suggestions. + +They are "soft" rules because they will not be a reason to reject a contribution +but if they are followed they will definitely make the lives of many people easier. -You -can validate your changes against the guide using [remark](https://github.com/remarkjs/remark-lint) which works as a -[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. Please ensure before submitting a contribution that you do not have any linter errors in your text editor. -You can also use [prettier](https://github.com/prettier/prettier) to automatically correct some of the style issues that might be found in the proposed changes. +- Start every sentence on a new line. + This then makes it easier to track with git where a change happened in the text. -We have deployed a continuous integrator ([circle CI](https://circleci.com/)) to further allow for integrating changes continuously. The CI is testing that the changes are inline with our standard styling. +- Similarly try to use "hard word wrapping": if a sentence gets long and extends + a line length beyond 80-100 characters, continue the sentence on the next line. -GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). +**Example** + +Don't do this: + +```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 +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. +``` + +- when providing a string example for a specific JSON key name make sure that this + example appears with double quotes as it would in the real JSON file. + +**Example** + +Don't do this: + +```markdown +| **Key name** | **Description** | +|--------------|----------------------------------------------------------| +| Manufacturer | Manufacturer of the equipment, for example (`Siemens`) | +``` + +That would look like this: + +| **Key name** | **Description** | +|--------------|----------------------------------------------------------| +| Manufacturer | Manufacturer of the equipment, for example (`Siemens`) | + +But do this instead: + +```markdown +| **Key name** | **Description** | +|--------------|----------------------------------------------------------| +| Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) | +``` + +That would look like this: + +| **Key name** | **Description** | +|--------------|----------------------------------------------------------| +| Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) | ## Building the specification using mkdocs -We are using mkdocs to render our specification. Please follow these instructions if you would like to build the specification locally. +We are using mkdocs to render our specification. +Please follow these instructions if you would like to build the specification locally. + +#### 1. Install mkdocs, the material theme and the required extensions -#### 1. Install mkdocs +In the following links, you can find more information about -To begin please follow [this link](https://www.mkdocs.org/#installation) to install mkdocs locally. +- [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`. + +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. + +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, +by using the following command: + +```bash +pip install -r requirements.txt +``` + +However this will also install some other packages you might not want to have (like `numpy`). +So if you only want to install what you need to build the specification, +use the following command: + +```bash +pip install \ + mkdocs \ + mkdocs-material \ + pymdown-extensions \ + mkdocs-branchcustomization-plugin \ + mkdocs-macros-plugin \ + tabulate +``` #### 2. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer -This can be done by clicking the green button on the right titled "Clone or download" +This can be done by clicking the green button on the right titled "Clone or +download" +or using [this link](https://github.com/bids-standard/bids-specification/archive/master.zip). + +#### 3. In the terminal (command line) navigate to your local version of the specification + +This location will have the same files you see on our +[main specification page](https://github.com/bids-standard/bids-specification). +Note: A finder window may not show the hidden files (those that start with a +period, like `.remarkrc`) + +#### 4. Ready to build! + +Using the terminal (command line) please enter `mkdocs serve`. +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 + +We use a linter called [Remarkjs](https://github.com/remarkjs/remark-lint) to +ensure all of our Markdown documents are consistent and well-styled. +This commonly produces errors, which are flagged by [GitHub Actions](https://github.com/features/actions), +a continuous integration service. +When GitHub Actions returns an error, use the following process to resolve the issue: + +### 1. Install NodeJS / npm + +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. + +### 2. Install Remark-CLI and our style guide + +Remark-CLI can be installed via [npm](https://www.npmjs.com/), which is part of +the NodeJS distribution. + +To install the packages we use for our style guide, the following command will +work on most command lines: + +```shell +npm install `cat npm-requirements.txt` +``` + +The equivalent command on PowerShell is: + +```shell +npm install @(cat npm-requirements.txt) +``` + +### 3. Find documents that are failing the check + +Run the following from the root directory of `bids-specification`: + +```shell +npx remark ./src/*.md ./src/*/*.md +``` + +### 4. Fix the flagged document + +Please go to the directory where the flagged file is and run remark like this: + +```shell +npx remark flagged_file.md -o flagged_file_fixed.md +``` + +Please confirm this has fixed the file. To do this, please run this: + +```shell +npx remark flagged_file_fixed.md --frail +``` + +This command will indicate whether this file now conforms to the style guide. +If it passes, replace `flagged_file.md` with the contents of +`flagged_file_fixed.md`, add and commit the change: + +```shell +mv flagged_file_fixed.md flagged_file.md +git add flagged_file.md +git commit -m 'STY: Fixed Markdown style' +``` -#### 3. Install our theme +NOTE: -Please go [here](https://squidfunk.github.io/mkdocs-material/) and install our theme - material. The terminal command is `pip install mkdocs-material` +Using `remark` to fix some linting errors might introduce some additional changes: -#### 4. In the terminal (command line) navigate to your local version of the specification +- changing unordered list from using `-` to using `*` +- changing ordered list from using `1.` to actually using the number of the item +- changes literal hyperlinks URLs from `[URL](URL)` to `` +- in some instances, it will "escape" all `_` and `&` with a `\` in all the URLs. -This location will have the same files you see on our [main specification page](https://github.com/bids-standard/bids-specification). Note: A finder window may not show the hidden files (those that start with a period i.e. .remarkrc) +You might have to revert those or use [interactive staging](https://git-scm.com/book/en/v2/Git-Tools-Interactive-Staging) to make sure you only commit the right chunks of code. -#### 5. Ready to build! +## Adding a figure to the specifications -Using the terminal (command line) please enter `mkdocs serve`. 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! +> A figure is worth a 1000 words! + +If you think that a figure or a picture can help summarize several aspects or notions of the +specification, do not hesitate to make a suggestion by showing a draft in a GitHub issue. + +After discussion and approval by the community, you can then submit your image +in a pull request. + +Images should be added to an `images` folder that is at the same level as the Markdown file +where your image will be added. For example if you want to add a figure `figure01.png` to +`src/05-derivatives/01-introduction.md` then your image should go to +`src/05-derivatives/images/figure01.png`. + +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 +![text to show if image does not load](relative_path_to_file "text to show when hovering over image") +``` +### Recommendations for figures + +1. Try to keep the file size of your figure relatively small (smaller than 500 Kb) +to keep the repository light and reduce the load time of the specs +for people who do not necessarily have broad-band internet. + +1. Figures in the main part of the specification should aim to be very "comprehensive" +but "smaller" figures can find their home in the appendices or the BIDS-starter-kit. + +1. If you are adding a figure (and not picture) make sure to also supply a vector format +of that figure (ideally as an `.svg` file) as this makes it easier to edit it in the +future. + +1. Try to include a README file that details where the figure / image came from +and how it can be reproduced. Preferably with a link to the file that generated the figure +if relevant. ## Making a change with a pull request -We appreciate all contributions to the BIDS Specification. **THANK YOU** for helping us build this useful resource. +We appreciate all contributions to the BIDS Specification. **THANK YOU** for +helping us build this useful resource. #### 1. Comment on an existing issue or open a new issue referencing your addition -This allows other members of the BIDS Specification team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. - +This allows other members of the BIDS Specification team to confirm that you +aren't overlapping with work that's currently underway and that everyone is on +the same page with the goal of the work you're going to carry out. #### 2. [Fork](https://help.github.com/articles/fork-a-repo/) [this repository](https://github.com/bids-standard/bids-specification) to your profile -This is now your own unique copy of the BIDS Specification. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the specification! +This is now your own unique copy of the BIDS Specification. +Changes here won't affect anyone else's work, so it's a safe space to explore edits to the +specification! -Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the master repository, otherwise you can end up with lots of dreaded [merge conflicts](https://help.github.com/articles/about-merge-conflicts/). +Make sure to +[keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) +with the master repository, otherwise you can end up with lots of dreaded +[merge conflicts](https://help.github.com/articles/about-merge-conflicts/). #### 3. Make the changes you've discussed -Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. Please detail the changes you are attempting to make. +Try to keep the changes focused. +If you submit a large amount of work in all in one go it will be much more work +for whomever is reviewing your pull request. +Please detail the changes you are attempting to make. #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) @@ -135,41 +427,214 @@ Please keep the title of your pull request short but informative - it will appear in the [changelog](src/CHANGES.md). Use one of the following prefixes in the title of your pull request: - - `[ENH]` - enhancement of the specification that adds a new feature or + +- `[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.) - - `[MISC]` - everything else including changes to the file listing +- `[FIX]` - fix of a typo or language clarification +- `[INFRA]` - changes to the infrastructure automating the specification + release (for example, building HTML docs) +- `[MISC]` - everything else including changes to the file listing contributors -If you are opening a pull request to obtain early feedback, but the changes -are not ready to be merged (a.k.a. Work in Progress pull request) please -use a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/). +If you are opening a pull request to obtain early feedback, but the changes are +not ready to be merged (also known as a "work in progress" pull request, sometimes abbreviated by `WIP`) +please use a +[draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/). -A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase. +A member of the BIDS Specification team will review your changes to confirm that +they can be merged into the main codebase. -A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation. +A [review](https://help.github.com/articles/about-pull-request-reviews/) will +usually consist of a few questions to help clarify the work you've done. +Keep an eye on your GitHub notifications and be prepared to join in that +conversation. -You can update your [fork](https://help.github.com/articles/about-forks/) of the BIDS Specification and the pull request will automatically update with those commits. You don't need to submit a new pull request when you make a change in response to a review. +You can update your [fork](https://help.github.com/articles/about-forks/) of the +BIDS Specification and the pull request will automatically update with those +commits. +You don't need to submit a new pull request when you make a change in +response to a review. -GitHub has a [nice introduction](https://help.github.com/articles/github-flow/) to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. +GitHub has a [nice introduction](https://help.github.com/articles/github-flow/) +to the pull request workflow, but please [get in touch](#get-in-touch) if you +have any questions. ## Example pull request -Example-Contribution -
-
+Example-Contribution +## Commenting on a pull request -## How the decision to merge a pull request is made? +Our primary method of adding to or enhancing BIDS occurs in the form of +[pull requests](https://help.github.com/articles/about-pull-requests/). +BIDS Extension Proposals +([BEPs](https://docs.google.com/document/d/1pWmEEY-1-WuwBPNy5tDAxVJYQ9Een4hZJM06tQZg8X4/)) +are submitted as pull requests, and commenting on pull requests is an important +way of participating in the BIDS community. + +This section outlines how to comment on a pull request. + +### Navigating to open pull requests + +The list of pull requests can be found by clicking on the "Pull requests" tab in +the +[BIDS-Specification repository](https://github.com/bids-standard/bids-specification). + +![BIDS-mainpage](commenting_images/BIDS_GitHub_mainpage.png "BIDS_GitHub_mainpage") + +### Selecting an open pull request + +In this example we will be navigating to our +[BIDS common derivatives pull request](https://github.com/bids-standard/bids-specification/pull/265). + +![BIDS-pr-list](commenting_images/BIDS_pr_list.png "BIDS_pr_list") + +### Pull request description + +Upon opening the pull request we see a detailed description of what this pull +request is seeking to address. +Descriptions are important for reviewers and the community to gain context into +what the pull request is achieving. + +![BIDS-pr](commenting_images/BIDS_pr.png "BIDS_pr") + +### Generally commenting on a pull request + +At the bottom of the pull request page, a comment box is provided for general +comments and questions. + +![BIDS-comment](commenting_images/BIDS_comment.png "BIDS-comment") + +### Specific comments on a pull request + +The proposed changes to the text of the specification can be seen in the "Files +changed" tab. +Proposed additions are displayed on a green background with a `+` +before each added line. +Proposed deletions are displayed on a red background with a `-` before each removed line. +To comment on a specific line, hover over it, and click the blue plus sign (pictured below). +Multiple lines can be selected by clicking and dragging the plus sign. + +![BIDS-specific-comment](commenting_images/BIDS_file_comment.png "BIDS-specific-comment") + +#### Suggesting text + +Comments on lines can contain "suggestions", which allow you to propose specific +wording for consideration. To make a suggestion, click the plus/minus (±) icon +in the comment box (pictured below). -The decision-making rules are outlined in [DECISION-MAKING.md](DECISION-MAKING.md). +![BIDS-suggest-box](commenting_images/BIDS_suggest.png "BIDS-suggest") + +Once the button is clicked the highlighted text will be copied into the comment +box and formatted as a +[Markdown code block](https://help.github.com/en/github/writing-on-github/creating-and-highlighting-code-blocks). + +![BIDS-suggest-text](commenting_images/BIDS_suggest_text.png "BIDS-suggest-box") + +The "Preview" tab in the comment box will show your suggestion as it will be +rendered. The "Suggested change" box will highlight the differences between the +original text and your suggestion. + +![BIDS-suggest-change](commenting_images/BIDS_suggest_change.png "BIDS-suggest-change") + +A comment may be submitted on its own by clicking "Add single comment". Several +comments may be grouped by clicking "Start a review". As more comments are +written, accept them with "Add review comment", and submit your review comments +as a batch by clicking the "Finish your review" button. + +## Accepting suggestion from a review + +When others are making [suggestions to your pull request](#suggesting-text), you +have the possibility to accept directly the changes suggested during the review +through the github interface. This can often be faster and more convenient than +make the changes locally and then pushing those changes to update your pull +request. Moreover it gives the opportunity to give credit to the reviewers for +their contribution. + +To do this, you must click on the `Files changed` tab at the top of the page of +a pull request. + +![BIDS_pr_files_changed](commenting_images/BIDS_pr_files_changed.png "BIDS_pr_files_changed") + +From there you can browse the different files changed and the 'diff' for each of +them (what line was changed and what the change consist of). You can also see +comments and directly change suggestions made by reviewers. + +You can add each suggestion one by one or group them together in a batch. + +![BIDS_pr_accept_comment](commenting_images/BIDS_pr_accept_comment.png "BIDS_pr_accept_comment") + +If you decide to batch the suggestions to add several of them at once, you must +scroll back to the top of the 'Files changed' page and the `commit suggestions` +button will let you add all those suggestions as a single commit. + +![BIDS_pr_commit_batch](commenting_images/BIDS_pr_commit_batch.png "BIDS_pr_commit_batch") + +Once those suggestions are committed the commit information should mention the +reviewer as a co-author. + +![BIDS_pr_reviewer_credit](commenting_images/BIDS_pr_reviewer_credit.png "BIDS_pr_reviewer_credit") + +## Making a change to the BIDS-schema + +Several aspects of the specification are defined in a set of YAML files in the +`src/schema` folder. The content of those files is described in a dedicated +[README file](./src/schema/README.md). + +### 1. Ensure that changes to the specification are matched in the schema + +The schema formalizes the rules described in the specification text, so you must +ensure that any changes which impact the rules of the specification (including, +but not limited to, adding new entities, suffixes, datatypes, modalities) are +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 + +As such, you need to ensure that the functions used throughout the specification to render these elements are appropriately referencing the schema. +In essence, please make sure, if your changes do impact how functions should be called, that you also update how the function are called. + +### 3. Render the specification with `mkdocs` to check your changes + +Run `mkdocs serve` and open `localhost:8000` to browse the rendered specification. +Make sure that all filename format templates, entity tables, and entity definitions are correct +and that the code that generates these elements is not broken by your changes. + +While the continuous integration run on pull requests by the repository will render the specification, +it is crucial to manually review the rendered changes to ensure that the code not only successfully runs, +but also that the rendered changes appear as expected. + +### 4. Push your changes + +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? +The decision-making rules are outlined in +[DECISION-MAKING.md](DECISION-MAKING.md). ## Recognizing contributions -BIDS follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md). +BIDS follows the +[all-contributors](https://github.com/kentcdodds/all-contributors) +specification, so we welcome and recognize all contributions from documentation +to testing to code development. +You can see a list of current contributors in the +[BIDS specification](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md). + +If you have made any type of contributions to the BIDS specifications, you can +either make a change to the +[contributors document](./src/99-appendices/01-contributors.md) and commit as +part of a pull request or you can edit this +[page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors) +of the specification WIKI. +The WIKI is then synced with the specification with evert new release of the specifications. ## Thank you! diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 4fb31490..ced7a616 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -2,8 +2,70 @@ ## Introduction -The Brain Imaging Data Structure (BIDS) community set out the following -decision-making rules with the intention to: +In October 2019, the BIDS community [voted](https://github.com/bids-standard/bids-specification/issues/355) +to ratify a governance structure and to elect five members as a *Steering Group* +to oversee the development and adoption of the standard. + +The document outlining our governance structure is hosted on the BIDS website: +[https://bids.neuroimaging.io/governance.html](https://bids.neuroimaging.io/governance.html) + +In the following, we list the current members of subgroups detailed in the +BIDS governance. + +### Steering Group + +| Name | +|------------------------------------------------------------------------------| +| Guiomar Niso ([@guiomar](https://github.com/guiomar)) | +| Melanie Ganz ([@melanieganz](https://github.com/melanieganz)) | +| Robert Oostenveld ([@robertoostenveld](https://github.com/robertoostenveld)) | +| Russell Poldrack ([@poldrack](https://github.com/poldrack)) | +| Kirstie Whitaker ([@KirstieJane](https://github.com/KirstieJane)) | + +### 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 | + +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. +Such a scope can range from maintaining a modality supported in the specification to nurturing a +welcoming BIDS community. +One or more scopes can be chosen by the maintainer and agreed upon by the Maintainers Group. +A maintainer is primarily responsible for issues within their chosen scope(s), although +contributions elsewhere are welcome, as well. + +### BEP Leads Group + +Leaders of BIDS Extension Proposals are listed in the +[table of BEPs](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification). + +### Contributors Group + +Contributors are listed in [Appendix I](https://bids-specification.readthedocs.io/en/stable/99-appendices/01-contributors.html) +of the BIDS specification. Contributors who have not yet entered their name +into this list are encouraged to edit the [Contributors WIKI page](https://github.com/bids-standard/bids-specification/wiki/Contributors) +with their name, using the emojis listed in the WIKI to indicate their +contributions. + +### Other groups + +The following groups not listed in detail. Please learn more about these groups +from the [governance document](https://bids.neuroimaging.io/governance.html). + +- BEP working groups +- Advisory Group +- BIDS Community + +## GitHub Workflow + +For the day-to-day work on the BIDS specification, we currently abide by the +following rules with the intention to: - Strive for consensus. - Promote open discussions. @@ -16,24 +78,6 @@ decision-making rules with the intention to: The rules outlined below are inspired by the [lazy consensus system used in the Apache Foundation](https://www.apache.org/foundation/voting.html) and heavily depends on [GitHub Pull Request Review system](https://help.github.com/articles/about-pull-requests/). -## Definitions - -**Repository** - [https://github.com/bids-standard/bids-specification](https://github.com/bids-standard/bids-specification) - -**Contributor** - a person listed in the Appendix I: Contributors. The -community decides on the content of this file using the same process as any -other change to the Repository (see below) allowing the meaning of "Contributor" -to evolve independently of the Decision-making rules. - -**Maintainer** - a Contributor responsible for the long term health of the -project and the community. Maintainers have additional rights (see Rules) -helping them to resolve conflicts and increase the pace of the development -when necessary. Current Maintainers: - -| Name | Time commitment | -|-----------------------------------------------------------------|-----------------| -| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | - ## Rules 1. Every modification of the specification (including a correction of a typo, @@ -42,7 +86,7 @@ when necessary. Current Maintainers: 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 - [CODEOWNERS](CODEOWNERS) file. + [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 evaluate it. @@ -55,12 +99,12 @@ when necessary. Current Maintainers: 1. Does not feature "WIP" in the title (Work in Progress). 1. Passes all automated tests. 1. Is not proposing a new release or has been approved by at least one - Maintainer (i.e., PRs proposing new releases need to be approved by at + Maintainer (that is, PRs proposing new releases need to be approved by at least one Maintainer). 1. A Maintainer can merge any PR - even if it's not eligible to merge according to Rule 4. 1. Any Contributor can Review a PR and Request changes. If a Contributor - Request changes they need to provide an explanation what changes + Requests changes they need to provide an explanation what changes should be added and justification of their importance. Reviews requesting changes can also be used to request more time to review a PR. 1. A Contributor that Requested changes can Dismiss their own review or Approve @@ -70,7 +114,7 @@ when necessary. Current Maintainers: their review or accepting the changes the Review can be Dismissed with a vote or by a Maintainer. Rules governing voting: 1. A Vote can be triggered by any Contributor, but only after 5 working days - from the time a Review Requesting Changes has been raised and in case a + from the time a Review Requesting changes has been raised and in case a Vote has been triggered previously no sooner than 15 working days since its conclusion. 1. Only Contributors can vote, each contributor gets one vote. @@ -80,7 +124,7 @@ when necessary. Current Maintainers: be added to it while a vote is ongoing. If a commit is accidentally made during that period it should be reverted. 1. The quorum for a Vote is 30% of all Contributors. - 1. The outcome of the vote is decided based on a simple majority. + 1. The outcome of the Vote is decided based on a simple majority. ## Comments @@ -94,12 +138,12 @@ when necessary. Current Maintainers: 1. To facilitate triage of incoming PR you can subscribe to notifications for new PRs proposing changes to specific files. To do this add your GitHub name next to the file you want to subscribe to in the - [CODEOWNERS](CODEOWNERS). This way you will be ask to review each relevant + [CODEOWNERS](./CODEOWNERS). This way you will be ask to review each relevant PR. Please mind that lack of your review will not prevent the PR from being 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 (i.e., +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 diff --git a/LICENSE b/LICENSE index 2f244ac8..d4466ac3 100644 --- a/LICENSE +++ b/LICENSE @@ -1,5 +1,7 @@ Attribution 4.0 International +Copyright (c) 2020, BIDS Contributors. + ======================================================================= Creative Commons Corporation ("Creative Commons") is not a law firm and diff --git a/Pipfile b/Pipfile deleted file mode 100644 index 535c0e0b..00000000 --- a/Pipfile +++ /dev/null @@ -1,14 +0,0 @@ -[[source]] -url = "https://pypi.org/simple" -verify_ssl = true -name = "pypi" - -[packages] -mkdocs = "==1.0.4" -mkdocs-material = "==4.1.2" -pymdown-extensions = "==6.0.0" - -[dev-packages] - -[requires] -python_version = "3.6" diff --git a/Pipfile.lock b/Pipfile.lock deleted file mode 100644 index e77134d2..00000000 --- a/Pipfile.lock +++ /dev/null @@ -1,148 +0,0 @@ -{ - "_meta": { - "hash": { - "sha256": "effb38045a509709aef13afe50f1022ab64a9855d99a958199709545b2095151" - }, - "pipfile-spec": 6, - "requires": { - "python_version": "3.6" - }, - "sources": [ - { - "name": "pypi", - "url": "https://pypi.org/simple", - "verify_ssl": true - } - ] - }, - "default": { - "click": { - "hashes": [ - "sha256:2335065e6395b9e67ca716de5f7526736bfa6ceead690adf616d925bdc622b13", - "sha256:5b94b49521f6456670fdb30cd82a4eca9412788a93fa6dd6df72c94d5a8ff2d7" - ], - "version": "==7.0" - }, - "jinja2": { - "hashes": [ - "sha256:065c4f02ebe7f7cf559e49ee5a95fb800a9e4528727aec6f24402a5374c65013", - "sha256:14dd6caf1527abb21f08f86c784eac40853ba93edb79552aa1e4b8aef1b61c7b" - ], - "version": "==2.10.1" - }, - "livereload": { - "hashes": [ - "sha256:78d55f2c268a8823ba499305dcac64e28ddeb9a92571e12d543cd304faf5817b", - "sha256:89254f78d7529d7ea0a3417d224c34287ebfe266b05e67e51facaf82c27f0f66" - ], - "version": "==2.6.1" - }, - "markdown": { - "hashes": [ - "sha256:2e50876bcdd74517e7b71f3e7a76102050edec255b3983403f1a63e7c8a41e7a", - "sha256:56a46ac655704b91e5b7e6326ce43d5ef72411376588afa1dd90e881b83c7e8c" - ], - "version": "==3.1.1" - }, - "markupsafe": { - "hashes": [ - "sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473", - "sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161", - "sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235", - "sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5", - "sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff", - "sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b", - "sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1", - "sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e", - "sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183", - "sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66", - "sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1", - "sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1", - "sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e", - "sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b", - "sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905", - "sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735", - "sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d", - "sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e", - "sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d", - "sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c", - "sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21", - "sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2", - "sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5", - "sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b", - "sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6", - "sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f", - "sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f", - "sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7" - ], - "version": "==1.1.1" - }, - "mkdocs": { - "hashes": [ - "sha256:17d34329aad75d5de604b9ed4e31df3a4d235afefdc46ce7b1964fddb2e1e939", - "sha256:8cc8b38325456b9e942c981a209eaeb1e9f3f77b493ad755bfef889b9c8d356a" - ], - "index": "pypi", - "version": "==1.0.4" - }, - "mkdocs-material": { - "hashes": [ - "sha256:8a572f4b3358b9c0e11af8ae319ba4f3747ebb61e2393734d875133b0d2f7891", - "sha256:91210776db541283dd4b7beb5339c190aa69de78ad661aa116a8aa97dd73c803" - ], - "index": "pypi", - "version": "==4.1.2" - }, - "pygments": { - "hashes": [ - "sha256:71e430bc85c88a430f000ac1d9b331d2407f681d6f6aec95e8bcfbc3df5b0127", - "sha256:881c4c157e45f30af185c1ffe8d549d48ac9127433f2c380c24b84572ad66297" - ], - "version": "==2.4.2" - }, - "pymdown-extensions": { - "hashes": [ - "sha256:25b0a7967fa697b5035e23340a48594e3e93acb10b06d74574218ace3347d1df", - "sha256:6cf0cf36b5a03b291ace22dc2f320f4789ce56fbdb6635a3be5fadbf5d7694dd" - ], - "index": "pypi", - "version": "==6.0" - }, - "pyyaml": { - "hashes": [ - "sha256:57acc1d8533cbe51f6662a55434f0dbecfa2b9eaf115bede8f6fd00115a0c0d3", - "sha256:588c94b3d16b76cfed8e0be54932e5729cc185caffaa5a451e7ad2f7ed8b4043", - "sha256:68c8dd247f29f9a0d09375c9c6b8fdc64b60810ebf07ba4cdd64ceee3a58c7b7", - "sha256:70d9818f1c9cd5c48bb87804f2efc8692f1023dac7f1a1a5c61d454043c1d265", - "sha256:86a93cccd50f8c125286e637328ff4eef108400dd7089b46a7be3445eecfa391", - "sha256:a0f329125a926876f647c9fa0ef32801587a12328b4a3c741270464e3e4fa778", - "sha256:a3c252ab0fa1bb0d5a3f6449a4826732f3eb6c0270925548cac342bc9b22c225", - "sha256:b4bb4d3f5e232425e25dda21c070ce05168a786ac9eda43768ab7f3ac2770955", - "sha256:cd0618c5ba5bda5f4039b9398bb7fb6a317bb8298218c3de25c47c4740e4b95e", - "sha256:ceacb9e5f8474dcf45b940578591c7f3d960e82f926c707788a570b51ba59190", - "sha256:fe6a88094b64132c4bb3b631412e90032e8cfe9745a58370462240b8cb7553cd" - ], - "version": "==5.1.1" - }, - "six": { - "hashes": [ - "sha256:3350809f0555b11f552448330d0b52d5f24c91a322ea4a15ef22629740f3761c", - "sha256:d16a0141ec1a18405cd4ce8b4613101da75da0e9a7aec5bdd4fa804d0e0eba73" - ], - "version": "==1.12.0" - }, - "tornado": { - "hashes": [ - "sha256:349884248c36801afa19e342a77cc4458caca694b0eda633f5878e458a44cb2c", - "sha256:398e0d35e086ba38a0427c3b37f4337327231942e731edaa6e9fd1865bbd6f60", - "sha256:4e73ef678b1a859f0cb29e1d895526a20ea64b5ffd510a2307b5998c7df24281", - "sha256:559bce3d31484b665259f50cd94c5c28b961b09315ccd838f284687245f416e5", - "sha256:abbe53a39734ef4aba061fca54e30c6b4639d3e1f59653f0da37a0003de148c7", - "sha256:c845db36ba616912074c5b1ee897f8e0124df269468f25e4fe21fe72f6edd7a9", - "sha256:c9399267c926a4e7c418baa5cbe91c7d1cf362d505a1ef898fde44a07c9dd8a5" - ], - "version": "==6.0.3" - } - }, - "develop": {} -} diff --git a/README.md b/README.md index b749e2b6..41136e0f 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -[![Build Status](https://travis-ci.com/bids-standard/bids-specification.svg?branch=master)](https://travis-ci.com/bids-standard/bids-specification) -[![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=svg)](https://circleci.com/gh/bids-standard/bids-specification) +[![Check Markdown style](https://github.com/bids-standard/bids-specification/actions/workflows/markdown_style.yml/badge.svg)](https://github.com/bids-standard/bids-specification/actions/workflows/markdown_style.yml) +[![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=shield)](https://circleci.com/gh/bids-standard/bids-specification) [![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard) - +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3686061.svg)](https://doi.org/10.5281/zenodo.3686061) bids-logo @@ -11,8 +11,37 @@ organisation of neuroimaging data. In this repository, we develop the [BIDS specification](https://bids-specification.readthedocs.io/en/latest/). -**Want to learn more about working with BIDS? Have a question, comment, or suggestion?** -Open or comment on one of our [NeuroStars issues](https://neurostars.org/tags/bids) or check out the [BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit)! +# When to use BIDS + +To organize your data in BIDS, all you need is neuro data, a computer, and the +[BIDS specification](https://bids-specification.readthedocs.io/en/stable/). + +BIDS currently supports the following data modalities with more to come in the future: + +- MRI +- MEG +- EEG +- iEEG +- behavioral +- physiological +- PET + +# Formatting your data with BIDS + +As a dataset curator, the GitHub repository and all files therein can be safely ignored. +Users should focus on [the rendered content](https://bids-specification.readthedocs.io/en/stable/). +The specification is provided in the form of a webpage, built using +[MkDocs](https://www.mkdocs.org/) and [Read the Docs](https://readthedocs.org/). + +*Want to learn more about working with BIDS? Have a question, comment, or suggestion?* + +1. Read some introductory material, most likely the very basic problems have already been addressed! + - [BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit) for tutorials, wikis, templates, ... +2. Post your question in one of several channels where BIDS members are active + - the [NeuroStars](https://neurostars.org/tags/bids) discourse forum + - the [BrainHack Mattermost](https://mattermost.brainhack.org), for instant messaging (see also this [news item](https://bids.neuroimaging.io/2020/06/24/Join-the-BIDS-community-on-the-BrainHack-Mattermost.html)) + - the [Google group](https://groups.google.com/forum/#!forum/bids-discussion), for broader discussions surrounding BIDS + - the [specification repository issue page](https://github.com/bids-standard/bids-specification/issues), if you found inconsistencies, typos, or other issues with the BIDS specification itself # Contributing to BIDS diff --git a/Release_Guideline.md b/Release_Guideline.md index 17aaf645..bba9f2aa 100644 --- a/Release_Guideline.md +++ b/Release_Guideline.md @@ -17,7 +17,7 @@ backwards-incompatible changes, while minor and patch releases must be backwards ## Guidelines Once a decision for a release has been established, the rules of [decision-making](DECISION-MAKING.md) -govern the mechanism of doing the release, *i.e.*, waiting 5 business days and obtaining +govern the mechanism of doing the release, meaning, waiting 5 business days and obtaining the approval of at least one maintainer before merging. ### Minor (1.X.0) releases @@ -32,7 +32,7 @@ Patch releases will generally be more frequent, and indicate less significant ch The following is a non-exhaustive set of justifications for a patch release: - A modality field has changed and the [bids-validator](https://github.com/bids-standard/bids-validator) has been updated to reflect this change. -- Links or information in the specification are no longer accurate, *e.g.* if a BEP document is added or moved +- Links or information in the specification are no longer accurate, for example if a BEP document is added or moved - The rendering of the [specification](https://bids-specification.readthedocs.io/en/stable/) has changed - A metadata field or file type is added at the request of a curator attempting to release BIDS-compliant data diff --git a/Release_Protocol.md b/Release_Protocol.md index 68c5dbd8..77e74e46 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -35,7 +35,7 @@ $ git fetch upstream $ git checkout -b rel/1.2.0 upstream/master ``` -### 2. Update the version and the contributors list +### 2. Update the version, contributors list, previous version URLs, and the Changelog Change the "Unreleased" heading in [src/CHANGES.md](https://github.com/bids-standard/bids-specification/blob/master/src/CHANGES.md) @@ -57,13 +57,28 @@ If the version preceding the `-dev` is not the target version, update the versio In the figure below, we update `v1.2.0-dev` to `v1.2.0`. ![dev-to-stable](release_images/site_name_release_1.2dev-1.2.png "dev-to-stable") -Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed. +Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed. Synchronize the [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md) with the [Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Contributors) to ensure all contributors are duly credited. Be sure not to remove credits if both have been edited. +Please change the previous version links from GitHub to ReadTheDocs. +In the figure below, we update v1.2.2. +![github-to-rtd](release_images/GitHub_to_RTD_spec_rendering.png "github-to-rtd") + +Remove `REL:` entries in [src/CHANGES.md](https://github.com/bids-standard/bids-specification/blob/master/src/CHANGES.md). + +```Diff +- REL: v1.2.2 #405 (franklin-feingold) +``` + +Review `src/CHANGES.md` to ensure that the document produces a changelog that is useful to a +reader of the specification. +For example, several small PRs fixing typos might be merged into a single line-item, or less +important changes might be moved down the list to ensure that large changes are more prominent. + ### 3. Commit changes and push to upstream By pushing `rel/` branches to the main repository, the chances of continuous integration @@ -76,7 +91,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" (*e.g.*, "REL: v1.2.0"). +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.** @@ -84,7 +99,7 @@ Minor revisions may be made using GitHub's [suggestion feature](https://help.github.com/en/articles/incorporating-feedback-in-your-pull-request). For larger changes, pull requests should be made against `master`. -**Merging other pull requests during this period requires agreement in this discussion.** +**Merging other pull requests during this period requires agreement among BIDS Maintainers.** There are no hard-and-fast rules for what other pull requests might be merged, but the focus should generally be on achieving a self-consistent, backwards-compatible document. @@ -95,22 +110,16 @@ probably wait. If `master` is updated, it should be merged into the `rel/` branch: ```Shell -$ get fetch upstream +$ git fetch upstream $ git checkout rel/1.2.0 $ git merge upstream/master $ git push rel/1.2.0 ``` -### 5. Clean the changelog +### 5. Set release date and merge -Review `src/CHANGES.md` to ensure that the document produces a changelog that is useful to a -reader of the specification. -For example, several small PRs fixing typos might be merged into a single line-item, or less -important changes might be moved down the list to ensure that large changes are more prominent. - -### 6. Set release date and merge - -On the day of release, the current date should be added to/updated in the changelog in the form +On the day of release, please ensure the release branch aligns with the master branch. +The current date should be added to/updated in the changelog in the form YYYY-MM-DD. The date should be placed after the link to the versioned URL. For example: @@ -122,6 +131,19 @@ For example: Verify that the pull request title matches "REL: vX.Y.Z" and merge the pull request. +### 6. Get the built PDF + +Upon each commit to the `master` branch, CircleCI builds a PDF version of the +specification (see `.circleci/config.yml` and the `pdf_build_src` directory). + +So after merging the new "stable" version into `master`, wait for the CircleCI +jobs to finish and then check the built PDF using this link: + +`https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master` + +Download the PDF and hold it ready for upload to our Zenodo archive. See the +*Uploading the stable PDF to Zenodo* step below. + ### 7. Tag the release GitHub's release mechanism does not have all of the features we need, so manually tag the release @@ -170,8 +192,8 @@ for `stable` and the most recent tag. ### 9. Edit the mkdocs.yml file site_name to set a new development version -Please submit a PR with the title `REL: -dev`. -This should be the first merged PR in the new version. +Please commit to `master` with the title `REL: -dev`. +This should be the first commit in the new version. This process is illustrated below. ![stable-to-dev](release_images/site_name_release_1.2-1.3dev.png "stable-to-dev") @@ -180,3 +202,25 @@ Note that the development version number should be larger than the last release, version of the next *intended* release, followed by `-dev`. For example, after the 1.3.0 release, either `1.3.1-dev` or `1.4.0-dev` would be reasonable, based on the expected next version. + +### 10. Uploading the stable PDF to Zenodo + +1. Open a private browser window +1. Log into https://github.com with the `bids-maintenance` user (credentials + are available from the BIDS maintainer group) +1. Open a new tab at https://zenodo.org and "log in via GitHub", you'll then + be on the `bids-maintenance` Zenodo account +1. Navigate to the [archive of our BIDS specification PDFs](https://doi.org/10.5281/zenodo.3686061) +1. Click on "add new version" +1. For a new version, upload the new PDF, naming it consistently with the other + PDFs: `BIDS-Specification-vX.X.X.pdf` (replace `X.X.X` with the new version) +1. Remove all other files from the upload +1. Edit the following fields: + 1. publication date + 1. version +1. Double check that everything is in order, then save and publish + +### 11. Sharing news of the release + +Please share news of the release on the [identified platforms](https://docs.google.com/spreadsheets/d/16SAGK3zG93WM2EWuoZDcRIC7ygPc5b7PDNGpFyC3obA/edit#gid=0). +Please use our previous release posts as a guide. diff --git a/TOC.md b/TOC.md deleted file mode 100644 index 7eb8399b..00000000 --- a/TOC.md +++ /dev/null @@ -1,136 +0,0 @@ -2 Table of contents -======================= - -[1 Changelog](#heading=h.17phlwhk50et) - -[2 Table of contents](#heading=h.zeylawffkwh9) - -[3 Introduction](#heading=h.ehs58l1sp5l0) -> [3.1 Motivation](#heading=h.nn0wr5qmclie) -> [3.2 Definitions](#heading=h.ld293tqw9us4) -> [3.3 Compulsory, optional, and additional data and -metadata](#heading=h.yic0v7leqtf3) -> [3.4 Source vs. raw vs. derived data](#heading=h.juzchuxblakl) -> [3.5 The Inheritance Principle](#heading=h.l5zwpkcouhem) -> [3.6 Extensions](#heading=h.18rh5sozhnxy) -> [3.7 Citing BIDS](#heading=h.bw5qroscmvib) - -[4 File Format specification](#heading=h.nx8ar720y0tv) -> [4.1 Imaging files](#heading=h.y0f2axq397vt) -> [4.2 Tabular files](#heading=h.r85srnfs3y24) ->> [4.2.1 Example:](#heading=h.fpjccp3z8lxv) ->> [4.2.2 Example:](#heading=h.o9t9l483hwh7) - -> [4.3 Key/value files (dictionaries)](#heading=h.c75m812a750g) ->> [4.3.1 Example:](#heading=h.str6bi80689r) - -[5 Participant names and other labels](#heading=h.8mzv4iyo50ug) - -[6 Units](#heading=h.ltev6sakv13v) - -[7 Directory structure](#heading=h.1vzzcnz6wczd) -> [7.1 Single session example](#heading=h.6hp4sl1q6arb) - -[8 Detailed file descriptions](#heading=h.v9uqdvt04vsf) -> [8.1 Dataset description](#heading=h.ie43v2mfgaeq) ->> [8.1.1 dataset_description.json](#heading=h.qza727avafid) ->> [8.1.2 README](#heading=h.yizt58dn4hby) ->> [8.1.3 CHANGES](#heading=h.732zmmqh1yq7) - -> [8.2 Code](#heading=h.csdrm1qizwq9) -> [8.3 Magnetic Resonance Imaging data](#heading=h.5k5g55vj6iy6) ->> [8.3.1 Common metadata fields](#heading=h.5u721tt1h9pe) ->> [8.3.2 Anatomy imaging data](#heading=h.fm6ipijipc08) ->> [8.3.3 Task (including resting state) imaging -data](#heading=h.r8mrcau3kkcq) ->>> [8.3.3.1 Example:](#heading=h.1q8p210od2f) - ->> [8.3.4 Diffusion imaging data](#heading=h.xfuiufnb319) ->>> [8.3.4.1 bvec example:](#heading=h.r9czn8f0t58k) ->>> [8.3.4.2 bval example:](#heading=h.e948atq2ku1n) ->>> [8.3.4.3 JSON example:](#heading=h.hxcaki8xqrp6) - ->> [8.3.5 Fieldmap data](#heading=h.fcegd01wpsf8) ->>> [8.3.5.1 Case 1: Phase difference image and at least one magnitude -image](#heading=h.fexn37cr2yum) ->>> [8.3.5.2 Case 2: Two phase images and two magnitude -images](#heading=h.dytrqt3rfo2y) ->>> [8.3.5.3 Case 3: A single, real fieldmap image (showing the field -inhomogeneity in each voxel)](#heading=h.9wqqfa1lqctc) ->>> [8.3.5.4 Case 4: Multiple phase encoded directions -(“pepolar”)](#heading=h.6gef31kvsx0l) - ->[8.4 Magnetoencephalography (MEG)](#heading=h.y1yw5l9a04g2) ->> [8.4.1 MEG recording data](#heading=h.ln9qkltewtqa) ->>>[8.4.1.1 Sidecar JSON document -(\*\_meg.json)](#heading=h.wmua3ist46l2) - ->> [8.4.2 Channels description table -(\*\_channels.tsv)](#heading=h.2ng8e4h6db4p) ->> [8.4.3 Coordinate System JSON document -(\*\_coordsystem.json)](#heading=h.vz4gpcbftsuu) ->> [8.4.4 Photos of the anatomical landmarks and/or head localization -coils (\*\_photo.jpg)](#heading=h.li6xt1s6zgjs) ->> [8.4.5 3-D head point /electrode locations file -(\*\_headshape.)](#heading=h.jrc7wyqvlzpp) ->> [8.4.6 Empty-room files (sub-emptyroom)](#heading=h.i7qifoac3vgf) - -> [8.5 Task events](#heading=h.daip42kp5ndz) ->> [8.5.1 Example:](#heading=h.akoyjl6f4i1e) ->> [8.5.2 Example:](#heading=h.gsp1xuuo09tb) ->> [8.5.3 Example:](#heading=h.8leve31f2d03) - -> [8.6 Physiological and other continuous -recordings](#heading=h.usbya6fhiy5v) ->> [8.6.1 Example:](#heading=h.mtd2764i6ii1) - -> [8.7 Behavioral experiments (with no -MRI)](#heading=h.cpt8jqa5g0y7) - -> [8.8 Scans file](#heading=h.rw11qtsldsuw) ->> [8.8.1 Example:](#heading=h.xtaf7kerpvji) - -> [8.9 Participant file](#heading=h.pi5iigxxt8vy) ->> [8.9.1 participants.tsv example:](#heading=h.rsax9zcpo17t) - -[9 Longitudinal studies with multiple sessions -(visits)](#heading=h.5c3b4lpzj5cn) -> [9.1 Sessions file](#heading=h.yba5gfw0vmht) ->> [9.1.1 Multiple sessions example:](#heading=h.ia2iiqnuitj) - -[10 Multi-site or multi-center studies](#heading=h.29tn5cduh4ci) -> [10.1 Option 1: Treat each site/center as a separate -dataset.](#heading=h.totu2lw0gxlj) -> [10.2 Option 2: Combining sites/centers into one -dataset](#heading=h.1t5ygwr3qrpq) - -[11 Appendix I: Contributors](#heading=h.hds2i7ii7hjo) - -[12 Appendix II: Licenses](#heading=h.8bxgvc9yrtig) - -[13 Appendix III: Hierarchical Event Descriptor (HED) -Tags](#heading=h.5sn36nhoj1fw) -> [13.1 Example:](#heading=h.rqz45nlfb5rx) -> [13.2 Example:](#heading=h.b382e7m2jzvb) - -[14 Appendix IV: Entity table](#heading=h.hj3w5z9pw4n7) - -[15 Appendix V: Units](#heading=h.h112sr17n2m2) - -[16 Appendix  VI: MEG file formats](#heading=h.l5rpo9atl5qp) -> [16.1 CTF](#heading=h.kzx3m7s518x2) -> [16.2 Elekta/Neuromag](#heading=h.a7ggx48p7aaf) -> [16.3 4D neuroimaging/BTi](#heading=h.gy0kbzisg1f1) -> [16.4 KIT/Yokogawa](#heading=h.2gmmxawyna7r) -> [16.5 KRISS](#heading=h.ts11elruq7kt) -> [16.6 ITAB](#heading=h.sgxhj770nor) -> [16.7 Aalto/MEG–MRI](#heading=h.moujhgczbkr9) - -[17 Appendix VII: preferred names of MEG -systems](#heading=h.bp5mugaep86u) - -[18 Appendix VIII: preferred names of Coordinate -systems](#heading=h.snhwsmgj62e1) -> [18.1 MEG specific Coordinate Systems](#heading=h.kfm2qyo3x0mo) -> [18.2 EEG specific Coordinate Systems](#heading=h.z9g5132tdpry) -> [18.2 Template based Coordinate Systems](#heading=h.qrh9iqfvccq5) diff --git a/commenting_images/BIDS_GitHub_mainpage.png b/commenting_images/BIDS_GitHub_mainpage.png new file mode 100644 index 00000000..08106280 Binary files /dev/null and b/commenting_images/BIDS_GitHub_mainpage.png differ diff --git a/commenting_images/BIDS_comment.png b/commenting_images/BIDS_comment.png new file mode 100644 index 00000000..76bbfbc1 Binary files /dev/null and b/commenting_images/BIDS_comment.png differ diff --git a/commenting_images/BIDS_comment_block.png b/commenting_images/BIDS_comment_block.png new file mode 100644 index 00000000..fdffcecc Binary files /dev/null and b/commenting_images/BIDS_comment_block.png differ diff --git a/commenting_images/BIDS_file_comment.png b/commenting_images/BIDS_file_comment.png new file mode 100644 index 00000000..08b02a0a Binary files /dev/null and b/commenting_images/BIDS_file_comment.png differ diff --git a/commenting_images/BIDS_pr.png b/commenting_images/BIDS_pr.png new file mode 100644 index 00000000..6799e109 Binary files /dev/null and b/commenting_images/BIDS_pr.png differ diff --git a/commenting_images/BIDS_pr_accept_comment.png b/commenting_images/BIDS_pr_accept_comment.png new file mode 100644 index 00000000..515da6d3 Binary files /dev/null and b/commenting_images/BIDS_pr_accept_comment.png differ diff --git a/commenting_images/BIDS_pr_commit_batch.png b/commenting_images/BIDS_pr_commit_batch.png new file mode 100644 index 00000000..35679f23 Binary files /dev/null and b/commenting_images/BIDS_pr_commit_batch.png differ diff --git a/commenting_images/BIDS_pr_files_changed.png b/commenting_images/BIDS_pr_files_changed.png new file mode 100644 index 00000000..8cb07c82 Binary files /dev/null and b/commenting_images/BIDS_pr_files_changed.png differ diff --git a/commenting_images/BIDS_pr_list.png b/commenting_images/BIDS_pr_list.png new file mode 100644 index 00000000..67c42615 Binary files /dev/null and b/commenting_images/BIDS_pr_list.png differ diff --git a/commenting_images/BIDS_pr_reviewer_credit.png b/commenting_images/BIDS_pr_reviewer_credit.png new file mode 100644 index 00000000..583f0f21 Binary files /dev/null and b/commenting_images/BIDS_pr_reviewer_credit.png differ diff --git a/commenting_images/BIDS_suggest.png b/commenting_images/BIDS_suggest.png new file mode 100644 index 00000000..b8b29630 Binary files /dev/null and b/commenting_images/BIDS_suggest.png differ diff --git a/commenting_images/BIDS_suggest_change.png b/commenting_images/BIDS_suggest_change.png new file mode 100644 index 00000000..3981481c Binary files /dev/null and b/commenting_images/BIDS_suggest_change.png differ diff --git a/commenting_images/BIDS_suggest_text.png b/commenting_images/BIDS_suggest_text.png new file mode 100644 index 00000000..54705a65 Binary files /dev/null and b/commenting_images/BIDS_suggest_text.png differ diff --git a/mkdocs.yml b/mkdocs.yml index 88fa7df3..66d3c57d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,5 @@ -site_name: Brain Imaging Data Structure v1.3.0-dev +site_name: Brain Imaging Data Structure v1.6.1-dev +site_url: https://bids-specification.readthedocs.io/en/stable/ theme: name: material custom_dir: theme_customizations/ @@ -12,6 +13,13 @@ markdown_extensions: - pymdownx.superfences plugins: - search + - branchcustomization: + update_config: + - branch: /(?!^master$)/ + +extra_css: + - css/watermark.css + - macros: + module_name: tools/mkdocs_macros_bidsschema/main docs_dir: 'src' use_directory_urls: false nav: @@ -23,25 +31,33 @@ nav: - Magnetic Resonance Imaging: 04-modality-specific-files/01-magnetic-resonance-imaging-data.md - Magnetoencephalography: 04-modality-specific-files/02-magnetoencephalography.md - Electroencephalography: 04-modality-specific-files/03-electroencephalography.md - - intracranial Electroencephalography: 04-modality-specific-files/04-intracranial-electroencephalography.md + - Intracranial Electroencephalography: 04-modality-specific-files/04-intracranial-electroencephalography.md - Task events: 04-modality-specific-files/05-task-events.md - Physiological and other continuous recordings: 04-modality-specific-files/06-physiological-and-other-continuous-recordings.md - - Behavioral experiments (with no MRI): 04-modality-specific-files/07-behavioral-experiments.md + - Behavioral experiments (with no neural recordings): 04-modality-specific-files/07-behavioral-experiments.md + - Genetic Descriptor: 04-modality-specific-files/08-genetic-descriptor.md + - Positron Emission Tomography: 04-modality-specific-files/09-positron-emission-tomography.md - Derivatives: - - Introduction: 05-derivatives/01-introduction.md - - Common data types: 05-derivatives/02-common-data-types.md + - BIDS Derivatives: 05-derivatives/01-introduction.md + - Common data types and metadata: 05-derivatives/02-common-data-types.md - Imaging data types: 05-derivatives/03-imaging.md + - Diffusion derivatives: 05-derivatives/05-diffusion-derivatives.md - Longitudinal and multi-site studies: 06-longitudinal-and-multi-site-studies.md - - Extending the BIDS specification: 07-extensions.md + - BIDS Extension Proposals: 07-extensions.md - Appendix: - Contributors: 99-appendices/01-contributors.md - Licenses: 99-appendices/02-licenses.md - - HED: 99-appendices/03-hed.md - - Entity-table: 99-appendices/04-entity-table.md + - Hierarchical Event Descriptors: 99-appendices/03-hed.md + - Entity table: 99-appendices/04-entity-table.md - Units: 99-appendices/05-units.md - MEG file formats: 99-appendices/06-meg-file-formats.md - MEG systems: 99-appendices/07-meg-systems.md - - Coordinate-systems: 99-appendices/08-coordinate-systems.md + - Coordinate systems: 99-appendices/08-coordinate-systems.md + - Entities: 99-appendices/09-entities.md + - File collections: 99-appendices/10-file-collections.md + - Quantitative MRI: 99-appendices/11-qmri.md + - Arterial Spin Labeling: 99-appendices/12-arterial-spin-labeling.md + - Cross modality correspondence: 99-appendices/13-cross-modality-correspondence.md - Changelog: CHANGES.md - The BIDS Starter Kit: - GitHub repository: https://github.com/bids-standard/bids-starter-kit diff --git a/npm-requirements.txt b/npm-requirements.txt new file mode 100644 index 00000000..7ef67d23 --- /dev/null +++ b/npm-requirements.txt @@ -0,0 +1,5 @@ +remark-cli@9.0.0 +remark-gfm@1 +remark-preset-lint-recommended@5.0.0 +remark-preset-lint-markdown-style-guide@4.0.0 +remark-lint-no-trailing-spaces@2 diff --git a/pdf_build_src/README.md b/pdf_build_src/README.md new file mode 100644 index 00000000..be74d31f --- /dev/null +++ b/pdf_build_src/README.md @@ -0,0 +1,49 @@ +# pdf-version of BIDS specification + +The `pdf_build_src` directory contains the scripts and `.tex` files required to build a pdf document of the BIDS specification from multiple markdown files using the pandoc library. + +[Pandoc](https://pandoc.org/index.html) is command line tool which is also a Haskell library that converts files from one markup format to another. + +## Requirements + +For the pdf build to be successful, the following need to be installed: + +- Python 3.6 or higher +- Numpy +- pandoc +- Latest version of LaTeX: By default, Pandoc creates PDFs using LaTeX. + Because a full MacTeX installation uses four gigabytes of disk space, + pandoc recommends BasicTeX or TinyTeX and using the tlmgr tool to install additional packages as needed. +- The [Symbola font](https://packages.ubuntu.com/search?keywords=fonts-symbola) that provides all emoji unicodes necessary to render the contributor icons in the PDF + +Installation instructions for both pandoc and LaTeX: https://pandoc.org/installing.html + +## Building pdf document + +Run the `build_pdf.sh` from the `pdf_build_src` with the command `sh build_pdf.sh` from the command line terminal + +## Technical Overview + +Pandoc comes with a plethora of options to format the resulting document. +For building a pdf from multiple markdowns, a consolidated intermediate tex file is first built, +which is then converted to a pdf document. +To achieve the desired formatting in the final pdf, +additional tex files are used with options offered by pandoc. + +### Formatting files + +- `metadata.yml` - Contains formatting options for the PDF. + +- `header_setup.tex` - This file sets up the packages to suit our needs. + +- `cover.tex` - BIDS Logo is used as a cover page for the document. `cover.tex` is used with the option `--include-before-body` + +- `header.tex` - Header tex file that's updated with the latest version number and date when `build_pdf.sh` is run. Used with the `-include-in-header` (or `-H`) option. + +### Scripts + +- `process_markdowns.py` - Script that processes markdown files in the `src` directory that are duplicated and modified for the needs of the pdf. + +- `pandoc_script.py` - Prepares and runs the final pandoc command through the `build_pdf.sh` script + +- `build_pdf.sh` - Shell script that organizes the directory structure and runs the above two python scripts diff --git a/pdf_build_src/build_pdf.sh b/pdf_build_src/build_pdf.sh new file mode 100755 index 00000000..fb5e9051 --- /dev/null +++ b/pdf_build_src/build_pdf.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Shell script that runs process_markdowns.py and pandoc_script.py in sequence to build the pdf document + +set -eu + +# prepare the copied src directory +python3 process_markdowns.py + +# copy pandoc_script into the temp src_copy directory +cp pandoc_script.py header.tex cover.tex header_setup.tex src_copy/src + +# run pandoc_script from src_copy directory +cd src_copy/src +python3 pandoc_script.py +mv bids-spec.pdf ../.. + +# delete the duplicated src directory +rm -rf src_copy diff --git a/pdf_build_src/cover.tex b/pdf_build_src/cover.tex new file mode 100644 index 00000000..ef979c76 --- /dev/null +++ b/pdf_build_src/cover.tex @@ -0,0 +1,25 @@ +% adds the bids logo as the cover page of the pdf +\begin{titlepage} + +\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here + +\center % Center everything on the page + + + +%---------------------------------------------------------------------------------------- +% LOGO SECTION +%---------------------------------------------------------------------------------------- + +\includegraphics[width=0.6\textwidth]{images/BIDS_logo.jpg}\\[-5cm] + +%---------------------------------------------------------------------------------------- +% TITLE SECTION +%---------------------------------------------------------------------------------------- + +\HRule \\[0.4cm] +{ \huge \bfseries Brain Imaging Data Structure Specification}\\[0.4cm] % Title of your document +\HRule \\[1.5cm] + +% \vfill % Fill the rest of the page with whitespace +% \textsc{\large v1.2.1}\\[0.5cm]{\large 2019-08-14}\\[2cm]\vfill\end{titlepage} diff --git a/pdf_build_src/header.tex b/pdf_build_src/header.tex new file mode 100644 index 00000000..279d4289 --- /dev/null +++ b/pdf_build_src/header.tex @@ -0,0 +1,7 @@ +% DO NOT EDIT THE 4 LINES BELOW THIS LINE (see `add_header` in process_markdowns.py) +\usepackage{fancyhdr} +\pagestyle{fancy} +\fancyhf{} +\fancyhead[L]{ Brain Imaging Data Structure v1.4.1-dev 2020-09-16 } +% Edit from here below +\fancyfoot[L]{\thepage} diff --git a/pdf_build_src/header_setup.tex b/pdf_build_src/header_setup.tex new file mode 100644 index 00000000..88358117 --- /dev/null +++ b/pdf_build_src/header_setup.tex @@ -0,0 +1,6 @@ +\usepackage{fontspec} +\setmainfont{Symbola} + +\usepackage[a4paper,margin=0.75in,landscape]{geometry} + +\rowcolors{1}{}{gray!10} diff --git a/pdf_build_src/metadata.yml b/pdf_build_src/metadata.yml new file mode 100644 index 00000000..3d8feb07 --- /dev/null +++ b/pdf_build_src/metadata.yml @@ -0,0 +1,8 @@ +--- +documentclass: report +classoption: table +colorlinks: true +linkcolor: blue +toc: true +listings: true +--- diff --git a/pdf_build_src/pandoc_script.py b/pdf_build_src/pandoc_script.py new file mode 100644 index 00000000..22c1e79d --- /dev/null +++ b/pdf_build_src/pandoc_script.py @@ -0,0 +1,68 @@ +"""Use the pandoc library as a final step to build the pdf. + +This is done once the duplicate src directory is processed. +""" +import os +import pathlib +import subprocess + + +def build_pdf(filename): + """Construct command with required pandoc flags and run using subprocess. + + Parameters + ---------- + filename : str + Name of the output file. + + """ + # Files that are not supposed to be built into the PDF + EXCLUDE = ["./index.md", "./schema/README.md", "./pregh-changes.md"] + + # Get all input files + markdown_list = [] + for root, dirs, files in os.walk('.'): + for file in files: + fpath = os.path.join(root, file) + if fpath.endswith(".md") and fpath not in EXCLUDE: + markdown_list.append(fpath) + elif fpath.endswith('index.md'): + # Special role for index.md + index_page = fpath + + # Prepare the command options + cmd = [ + 'pandoc', + '--from=markdown_github+yaml_metadata_block', + '--include-before-body=./cover.tex', + '--include-in-header=./header.tex', + '--include-in-header=./header_setup.tex', + '--pdf-engine=xelatex', + '--output={}'.format(filename), + ] + + # location of this file: This is also the working directory when + # the pdf is being built using `cd build_pdf_src` and then + # `bash build_pdf.sh` + root = pathlib.Path(__file__).parent.absolute() + + # Resources are searched relative to the working directory, but + # we can add additional search paths using :, ... + # When in one of the 99-appendices/ files there is a reference to + # "../04-modality-specific-files/images/...", then we need to use + # 99-appendices/ as a resource-path so that the relative files can + # be found. + cmd += [f'--resource-path=.:{str(root / "99-appendices")}'] + + # Add input files to command + # The filenames in `markdown_list` will ensure correct order when sorted + cmd += [str(root / index_page)] + cmd += [str(root / i) for i in ["../../metadata.yml"] + sorted(markdown_list)] + + # print and run + print('running: \n\n' + '\n'.join(cmd)) + subprocess.run(cmd) + + +if __name__ == "__main__": + build_pdf('bids-spec.pdf') diff --git a/pdf_build_src/process_markdowns.py b/pdf_build_src/process_markdowns.py new file mode 100644 index 00000000..112c366b --- /dev/null +++ b/pdf_build_src/process_markdowns.py @@ -0,0 +1,498 @@ +"""Process the markdown files. + +The purpose of the script is to create a duplicate src directory within which +all of the markdown files are processed to match the specifications of building +a pdf from multiple markdown files using the pandoc library (***add link to +pandoc library documentation***) with pdf specific text rendering in mind as +well. +""" + +import os +import re +import subprocess +import sys +from datetime import datetime + +import numpy as np + +sys.path.append("../tools/") +from schemacode import macros + + +def run_shell_cmd(command): + """Run shell/bash commands passed as a string using subprocess module.""" + process = subprocess.Popen(command.split(), stdout=subprocess.PIPE, + stderr=subprocess.PIPE) + output = process.stdout.read() + + return output.decode('utf-8') + + +def copy_src(): + """Duplicate src directory to a new but temp directory named 'src_copy'.""" + # source and target directories + src_path = "../src/" + target_path = "src_copy" + + # make new directory + mkdir_cmd = "mkdir "+target_path + run_shell_cmd(mkdir_cmd) + + # copy contents of src directory + copy_cmd = "cp -R "+src_path+" "+target_path + run_shell_cmd(copy_cmd) + + +def copy_bids_logo(): + """Copy BIDS_logo.jpg from the BIDS_logo dir in the root of the repo.""" + run_shell_cmd("cp ../BIDS_logo/BIDS_logo.jpg src_copy/src/images/") + + +def copy_images(root_path): + """Copy images. + + Will be done from images directory of subdirectories to images directory + in the src directory + """ + subdir_list = [] + + # walk through the src directory to find subdirectories named 'images' + # and copy contents to the 'images' directory in the duplicate src + # directory + for root, dirs, files in sorted(os.walk(root_path)): + if 'images' in dirs: + subdir_list.append(root) + + for each in subdir_list: + if each != root_path: + run_shell_cmd("cp -R "+each+"/images"+" "+root_path+"/images/") + + +def extract_header_string(): + """Extract the latest release's version number and date from CHANGES.md.""" + run_shell_cmd("cp ../mkdocs.yml src_copy/") + + with open(os.path.join(os.path.dirname(__file__), 'src_copy/mkdocs.yml'), 'r') as file: + data = file.readlines() + + header_string = data[0].split(": ")[1] + + title = " ".join(header_string.split()[0:4]) + version_number = header_string.split()[-1] + build_date = datetime.today().strftime('%Y-%m-%d') + + return title, version_number, build_date + + +def add_header(): + """Add the header string extracted from changelog to header.tex file.""" + title, version_number, build_date = extract_header_string() + header = " ".join([title, version_number, build_date]) + + # creating a header string with latest version number and date + header_string = (r"\fancyhead[L]{ " + header + " }") + + with open('header.tex', 'r') as file: + data = file.readlines() + + # insert the header, note that you have to add a newline + data[4] = header_string+'\n' + + # re-write header.tex file with new header string + with open('header.tex', 'w') as file: + file.writelines(data) + + +def remove_internal_links(root_path, link_type): + """Find and replace all cross and same markdown internal links. + + The links will be replaced with plain text associated with it. + """ + if link_type == 'cross': + # regex that matches cross markdown links within a file + # TODO: add more documentation explaining regex + primary_pattern = re.compile(r'\[((?!http).[\w\s.\(\)`*/–]+)\]\(((?!http).+(\.md|\.yml|\.md#[\w\-\w]+))\)') # noqa: E501 + elif link_type == 'same': + # regex that matches references sections within the same markdown + primary_pattern = re.compile(r'\[([\w\s.\(\)`*/–]+)\]\(([#\w\-._\w]+)\)') + + for root, dirs, files in sorted(os.walk(root_path)): + for file in files: + if file.endswith(".md"): + with open(os.path.join(root, file), 'r') as markdown: + data = markdown.readlines() + + for ind, line in enumerate(data): + match = primary_pattern.search(line) + + if match: + line = re.sub(primary_pattern, + match.group().split('](')[0][1:], line) + + data[ind] = line + + with open(os.path.join(root, file), 'w') as markdown: + markdown.writelines(data) + + +def modify_changelog(): + """Change first line of the changelog to markdown Heading 1. + + This modification makes sure that in the pdf build, changelog is a new + chapter. + """ + with open('src_copy/src/CHANGES.md', 'r') as file: + data = file.readlines() + + data[0] = "# Changelog" + + with open('src_copy/src/CHANGES.md', 'w') as file: + file.writelines(data) + + +def correct_table(table, offset=[0.0, 0.0], debug=False): + """Create the corrected table. + + Compute the number of characters maximal in each table column and reformat each + row in the table to make sure the first and second rows of the table have enough + dashes (in proportion) and that fences are correctly aligned + for correct rendering in the generated PDF. + + Parameters + ---------- + table : list of list of str + Table content extracted from the markdown file. + offset : list of int + Offset that is used to adjust the correction of number of dashes in the first (offset[0]) and + second (offset[1]) columns by the number specified in percentage. Defaults to [0.0, 0.0]. + debug : bool + If True, print debugging information. Defaults to False. + + Returns + ------- + new_table : list of list of str + List of corrected lines of the input table with corrected number of dashes and aligned fences. + To be later joined with pipe characters (``|``). + """ + # nb_of_rows = len(table) + nb_of_cols = len(table[0]) - 2 + + nb_of_chars = [] + for i, row in enumerate(table): + # Ignore number of dashes in the count of characters + if i != 1: + nb_of_chars.append([len(elem) for elem in row]) + + # sanity check: nb_of_chars is list of list, all nested lists must be of equal length + if not len(set([len(i) for i in nb_of_chars])) == 1: + print('ERROR for current table ... "nb_of_chars" is misaligned, see:\n') + print(nb_of_chars) + print('\nSkipping formatting of this table.\n') + return table + + # Convert the list to a numpy array and computes the maximum number of chars for each column + nb_of_chars_arr = np.array(nb_of_chars) + max_chars_in_cols = nb_of_chars_arr.max(axis=0) + max_chars = max_chars_in_cols.max() + + # Computes an equal number of dashes per column based on the maximal number of characters over the columns + nb_of_dashes = max_chars + prop_of_dashes = 1.0 / nb_of_cols + + # Adjust number of characters in first and second column based offset parameter + first_column_width = int(offset[0] * nb_of_dashes) + nb_of_dashes + second_column_width = int(offset[1] * nb_of_dashes) + nb_of_dashes + + if debug: + print(' - Number of chars in table cells: {}'.format(max_chars_in_cols)) + print(' - Number of dashes (per column): {}'.format(nb_of_dashes)) + print(' - Proportion of dashes (per column): {}'.format(prop_of_dashes)) + print(' - Final number of chars in first column: {}'.format(first_column_width)) + print(' - Final number of chars in second column: {}'.format(second_column_width)) + + # Format the lines with correct number of dashes or whitespaces and + # correct alignment of fences and populate the new table (A List of str) + new_table = [] + for i, row in enumerate(table): + + if i == 1: + str_format = ' {:-{align}{width}} ' + else: + str_format = ' {:{align}{width}} ' + + row_content = [] + for j, elem in enumerate(row): + # Set the column width + column_width = nb_of_dashes + if j == 1: + column_width = first_column_width + elif j == 2: + column_width = second_column_width + + if j == 0 or j == len(row) - 1: + row_content.append(elem) + else: + # Handles alignment descriptors in pipe tables + if '-:' in elem and ':-' in elem: + str_format = ' {:-{align}{width}}: ' + row_content.append(str_format.format(':-', align='<', width=(column_width))) + elif '-:' not in elem and ':-' in elem: + str_format = ' {:-{align}{width}} ' + row_content.append(str_format.format(':-', align='<', width=(column_width))) + elif '-:' in elem and ':-'not in elem: + str_format = ' {:-{align}{width}}: ' + row_content.append(str_format.format('-', align='<', width=(column_width))) + elif i == 1 and '-:' not in elem and ':-' not in elem: + str_format = ' {:-{align}{width}} ' + row_content.append(str_format.format('-', align='<', width=(column_width))) + else: + row_content.append(str_format.format(elem, align='<', width=(column_width))) + + new_table.append(row_content) + + return new_table + + +def _contains_table_start(line, debug=False): + """Check if line is start of a md table.""" + is_table = False + + nb_of_pipes = line.count('|') + nb_of_escaped_pipes = line.count(r'\|') + nb_of_pipes = nb_of_pipes - nb_of_escaped_pipes + nb_of_dashes = line.count('-') + + if debug: + print('Number of dashes / pipes : {} / {}'.format(nb_of_dashes, nb_of_pipes)) + + if nb_of_pipes > 2 and nb_of_dashes > 2: + is_table = True + + return is_table + + +def correct_tables(root_path, debug=False): + """Change tables in markdown files for correct rendering in PDF. + + This modification makes sure that the proportion and number of dashes (-) are + sufficient enough for correct PDF rendering and fences (|) are correctly aligned. + + + Parameters + ---------- + root_path : str + Path to the root directory containing the markdown files + debug : bool + If True, print debugging information. Defaults to False. + + Notes + ----- + This function MUST respect escaped pipes (i.e., pipes preceded by a backslash), + and not interpret them as table delimiters. Here this is implemented with a regex + split and a negative lookbehind assertion [1]_. + + References + ---------- + .. [1] https://stackoverflow.com/a/21107911/5201771 + """ + exclude_files = ['index.md', '01-contributors.md'] + for root, dirs, files in sorted(os.walk(root_path)): + for file in files: + if file.endswith(".md") and file not in exclude_files: + print('Check tables in {}'.format(os.path.join(root, file))) + + # Load lines of the markdown file + with open(os.path.join(root, file), 'r') as f: + content = f.readlines() + + table_mode = False + start_line = 0 + new_content = [] + for line_nb, line in enumerate(content): + # Use dashes to detect where a table start and + # extract the header and the dashes lines + if not table_mode and _contains_table_start(line, debug): + # Initialize a list to store table rows + table = [] + + # Set table_mode to True such that the next lines + # will be append to the table list + table_mode = True + + # Keep track of the line number where the table starts + start_line = line_nb-1 + + print(' * Detected table starting line {}'.format(start_line)) + # Extract for each row (header and the one containing dashes) + # the content of each column and strip to remove extra whitespace + header_row = [c.strip() for c in re.split(r'(? 1) + is_end_of_table = False + if len(row) > 1: + table.append(row) + if line_nb < len(content) - 1: + if not len(content[line_nb]) > 1: + is_end_of_table = True + end_line = line_nb + elif line_nb == len(content) - 1: + is_end_of_table = True + end_line = line_nb + else: + is_end_of_table = True + end_line = line_nb - 1 + + # If the end of the table is reached, correct the table and + # append each corrected row (line) to the content of the new markdown content + if is_end_of_table: + print(' - End of table detected after line {}'.format(end_line)) + + # Set table_mode to False such that the script will look + # for a new table start at the next markdown line + table_mode = False + + # Correct the given table + table = correct_table(table, debug=debug) + print(' - Table corrected') + if debug: + print(table) + + # Update the corresponding lines in + # the markdown with the corrected table + count = 0 + for i, new_line in enumerate(content): + if i == start_line: + new_content.pop() + if i >= start_line and i < end_line: + new_content.append('|'.join(table[count])+' \n') + count += 1 + elif i == end_line: + new_content.append('|'.join(table[count])+' \n\n') + count += 1 + print(' - Appended corrected table lines to the new markdown content') + else: + new_content.append(line) + + line_nb += 1 + + # Overwrite with the new markdown content + with open(os.path.join(root, file), 'w') as f: + f.writelines(new_content) + + +def edit_titlepage(): + """Add title and version number of the specification to the titlepage.""" + title, version_number, build_date = extract_header_string() + + with open('cover.tex', 'r') as file: + data = file.readlines() + + data[-1] = ("\\textsc{\large "+version_number+"}" + + "\\\\[0.5cm]" + + "{\large " + + build_date + + "}" + + "\\\\[2cm]" + + "\\vfill" + + "\\end{titlepage}") + + with open('cover.tex', 'w') as file: + data = file.writelines(data) + + +def process_macros(duplicated_src_dir_path): + """Search for mkdocs macros in the specification, run the embedded + functions, and replace the macros with their outputs. + + Parameters + ---------- + duplicated_src_dir_path : str + Location of the files from the specification. + + Notes + ----- + Macros are embedded snippets of Python code that are run as part of the + mkdocs build, when generating the website version of the specification. + + Warning + ------- + This function searches specifically for the mkdocs macros plugin's + delimiters ("{{" and "}}"). Therefore, those characters should not be used + in the specification for any purposes other than running macros. + """ + for root, dirs, files in os.walk(duplicated_src_dir_path): + for name in files: + # Only edit markdown files + if not name.lower().endswith(".md"): + continue + + filename = os.path.join(root, name) + with open(filename, "r") as fo: + contents = fo.read() + + # Replace code snippets in the text with their outputs + matches = re.findall("({{.*?}})", contents) + for m in matches: + # Remove macro delimiters to get *just* the function call + function_string = m.strip("{} ") + # Replace prefix with module name + function_string = function_string.replace( + "MACROS___", + "macros." + ) + # Run the function to get the output + new = eval(function_string) + # Replace the code snippet with the function output + contents = contents.replace(m, new) + + with open(filename, "w") as fo: + fo.write(contents) + + +if __name__ == '__main__': + + duplicated_src_dir_path = 'src_copy/src' + + # Step 1: make a copy of the src directory in the current directory + copy_src() + + # Step 2: run mkdocs macros embedded in markdown files + process_macros(duplicated_src_dir_path) + + # Step 3: copy BIDS_logo to images directory of the src_copy directory + copy_bids_logo() + + # Step 4: copy images from subdirectories of src_copy directory + copy_images(duplicated_src_dir_path) + subprocess.call("mv src_copy/src/images/images/* src_copy/src/images/", + shell=True) + + # Step 5: extract the latest version number, date and title + extract_header_string() + add_header() + + edit_titlepage() + + # Step 6: modify changelog to be a level 1 heading to facilitate section + # separation + modify_changelog() + + # Step 7: remove all internal links + remove_internal_links(duplicated_src_dir_path, 'cross') + remove_internal_links(duplicated_src_dir_path, 'same') + + # Step 8: correct number of dashes and fences alignment for rendering tables in PDF + correct_tables(duplicated_src_dir_path) diff --git a/pull_request_template.md b/pull_request_template.md deleted file mode 100644 index 07211dfc..00000000 --- a/pull_request_template.md +++ /dev/null @@ -1,18 +0,0 @@ ---- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST --- - -- Please keep the title of your pull request short but informative - it will - appear in the changelog -- 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. -- 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 etc.) - - `[MISC]` - everything else including changes to the file listing - contributors -- If you are opening a pull request to obtain early feedback, but the changes - are not ready to be merged (a.k.a. Work in Progress pull request) please - use a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) - ---- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- diff --git a/readthedocs.yml b/readthedocs.yml index 59d9418a..f8ded24a 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -6,7 +6,7 @@ build: image: latest python: - version: 3.6 + version: 3.8 install: - requirements: requirements.txt diff --git a/release_images/GitHub_to_RTD_spec_rendering.png b/release_images/GitHub_to_RTD_spec_rendering.png new file mode 100644 index 00000000..ec04d4e2 Binary files /dev/null and b/release_images/GitHub_to_RTD_spec_rendering.png differ diff --git a/requirements.txt b/requirements.txt index 898468cb..806c28a3 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1 +1,9 @@ -mkdocs-material \ No newline at end of file +mkdocs>=1.1 +mkdocs-material>=5.4 +pymdown-extensions>=7.0.0 +mkdocs-branchcustomization-plugin~=0.1.3 +mkdocs-macros-plugin +numpy +pandas +PYYaml +tabulate diff --git a/src/01-introduction.md b/src/01-introduction.md index ad06f725..79ce0831 100644 --- a/src/01-introduction.md +++ b/src/01-introduction.md @@ -7,7 +7,7 @@ different ways. So far there is no consensus how to organize and share data obtained in neuroimaging experiments. Even two researchers working in the same lab can opt to arrange their data in a different way. Lack of consensus (or a standard) leads to misunderstandings and time wasted on rearranging data or -rewriting scripts expecting certain structure. Here we describe a simple and +rewriting scripts expecting certain structure. Here we describe a simple and easy-to-adopt way of organising neuroimaging and behavioral data. By using this standard you will benefit in the following ways: @@ -18,24 +18,26 @@ standard you will benefit in the following ways: time. By using BIDS you will save time trying to understand and reuse data acquired by a graduate student or postdoc that has already left the lab. -- There are a growing number of data analysis software packages that can - understand data organised according to BIDS (see - [http://bids.neuroimaging.io](http://bids.neuroimaging.io) for the most up - to date list). +- There are a growing number of data analysis software packages that can + understand data organised according to BIDS (see the + [up to date list](https://bids.neuroimaging.io/benefits.html)). -- Databases such as OpenNeuro.org accept datasets organised according to BIDS. +- Databases such as [OpenNeuro.org](https://openneuro.org/) accept datasets + organised according to BIDS. If you ever plan to share your data publicly (nowadays some journals require this) you can minimize the additional time and energy spent on publication, and speed up the curation process by using BIDS to structure and describe your data right after acquisition. -- There are [validation tools](https://github.com/Squishymedia/BIDS-Validator) - that can check your dataset integrity and let you easily spot missing - values. +- Validation tools such as the [BIDS Validator](https://github.com/bids-standard/bids-validator) + can check your dataset integrity and help you easily spot missing values. -BIDS is heavily inspired by the format used internally by OpenfMRI.org and has -been supported by the International Neuroinformatics Coordinating Facility and -the Neuroimaging Data Sharing Task Force. While working on BIDS we consulted +BIDS was heavily inspired by the format used internally by the OpenfMRI repository +that is now known as [OpenNeuro.org](https://openneuro.org/), +and has been supported by the International Neuroinformatics Coordinating Facility +([INCF](https://www.incf.org/)) +and the INCF Neuroimaging Data Sharing (NIDASH) Task Force. +While working on BIDS we consulted many neuroscientists to make sure it covers most common experiments, but at the same time is intuitive and easy to adopt. The specification is intentionally based on simple file formats and folder structures to reflect current lab @@ -46,24 +48,92 @@ different backgrounds. The BIDS specification can be extended in a backwards compatible way and will evolve over time. This is accomplished through community-driven BIDS Extension -Proposals (BEPs). For more information about the BEP process, and list of -current BEP proposals, see [Extending the BIDS specification](07-extensions.md). +Proposals (BEPs). For more information about the BEP process, see +[Extending the BIDS specification](07-extensions.md). ## Citing BIDS -When referring to BIDS in context of academic literature please cite: +When referring to BIDS in context of academic literature, please cite one or +more of the publications listed below. +We RECOMMEND that you cite the original publication on BIDS and *additionally* +the publication regarding the datatype you were using +(for example, EEG, MEG, iEEG, if available). -> Gorgolewski, K.J., Auer, T., Calhoun, V.D., Craddock, R.C., Das, S., Duff, -> E.P., Flandin, G., Ghosh, S.S., Glatard, T., Halchenko, Y.O., Handwerker, -> D.A., Hanke, M., Keator, D., Li, X., Michael, Z., Maumet, C., Nichols, B.N., -> Nichols, T.E., Pellman, J., Poline, J.-B., Rokem, A., Schaefer, G., Sochat, -> V., Triplett, W., Turner, J.A., Varoquaux, G., Poldrack, R.A., 2016. -> [The brain imaging data structure, a format for organizing and describing outputs of neuroimaging experiments](https://www.nature.com/articles/sdata201644). -> Sci Data 3, 160044. +For example: -as well as other papers describing specific BIDS extensions (see below). +> The data used in the study were organized using the +> Brain Imaging Data Structure (Gorgolewski, K., Auer, T., Calhoun, V. et al., 2016) +> with the extension for EEG data (Pernet, C.R., Appelhoff, S., Gorgolewski, K.J. et al., 2019). + +### Original publication + +- Gorgolewski, K.J., Auer, T., Calhoun, V.D., Craddock, R.C., Das, S., Duff, + E.P., Flandin, G., Ghosh, S.S., Glatard, T., Halchenko, Y.O., Handwerker, + D.A., Hanke, M., Keator, D., Li, X., Michael, Z., Maumet, C., Nichols, B.N., + Nichols, T.E., Pellman, J., Poline, J.-B., Rokem, A., Schaefer, G., Sochat, + V., Triplett, W., Turner, J.A., Varoquaux, G., Poldrack, R.A. (2016). + **The brain imaging data structure,** + **a format for organizing and describing outputs of neuroimaging experiments**. + Scientific Data, 3 (160044). + [doi:10.1038/sdata.2016.44](https://doi.org/10.1038/sdata.2016.44) + +### Datatype specific publications + +#### EEG + +- Pernet, C. R., Appelhoff, S., Gorgolewski, K.J., Flandin, G., Phillips, C., + Delorme, A., Oostenveld, R. (2019). + **EEG-BIDS, an extension to the brain imaging data structure for electroencephalography**. + Scientific data, 6 (103). + [doi:10.1038/s41597-019-0104-8](https://doi.org/10.1038/s41597-019-0104-8) + +#### iEEG + +- Holdgraf, C., Appelhoff, S., Bickel, S., Bouchard, K., D'Ambrosio, S., + David, O., Devinsky, O., Dichter, B., Flinker, A., Foster, B. L., + Gorgolewski, K. J., Groen, I., Groppe, D., Gunduz, A., Hamilton, L., + Honey, C. J., Jas, M., Knight, R., Lauchaux, J.-P., Lau, J. C., + Lee-Messer, C., Lundstrom, B. N., Miller, K. J., Ojemann, J. G., + Oostenveld, R., Petridou, N., Piantoni, G., Pigorini, A., Pouratian, N., + Ramsey, N. F., Stolk, A., Swann, N. C., Tadel, F., Voytek, B., Wandell, B. A., + Winawer, J., Whitaker, K., Zehl, L., Hermes, D. (2019). + **iEEG-BIDS, extending the Brain Imaging Data Structure specification to** + **human intracranial electrophysiology**. + Scientific data, 6 (102). + [doi:10.1038/s41597-019-0105-7](https://doi.org/10.1038/s41597-019-0105-7) + +#### MEG + +- Niso Galan, J.G., Gorgolewski, K.J., Bock, E., Brooks, T.L., Flandin, G., + Gramfort, A., Henson, R.N., Jas, M., Litvak, V., Moreau, J., Oostenveld, R., + Schoffelen, J.-M., Tadel, F., Wexler, J., Baillet, S. (2018). + **MEG-BIDS, the brain imaging data structure extended to magnetoencephalography**. + Scientific Data, 5 (180110). + [doi:10.1038/sdata.2018.110](https://doi.org/10.1038/sdata.2018.110) + +#### PET + +- Knudsen GM, Ganz M, Appelhoff S, Boellaard R, Bormans G, Carson RE, Catana C, + Doudet D, Gee AD, Greve DN, Gunn RN, Halldin C, Herscovitch P, Huang H, Keller SH, + Lammertsma AA, Lanzenberger R, Liow JS, Lohith TG, Lubberink M, Lyoo CH, Mann JJ, + Matheson GJ, Nichols TE, Nørgaard M, Ogden T, Parsey R, Pike VW, Price J, Rizzo G, + Rosa-Neto P, Schain M, Scott PJH, Searle G, Slifstein M, Suhara T, Talbot PS, + Thomas A, Veronese M, Wong DF, Yaqub M, Zanderigo F, Zoghbi S, Innis RB. (2020). + **Guidelines for Content and Format of PET Brain Data in Publications and in Archives: A Consensus Paper**. + Journal of Cerebral Blood Flow and Metabolism, 2020 Aug; 40(8): 1576-1585. + [doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433) + +#### Genetics + +- Clara Moreau, Martineau Jean-Louis, Ross Blair, Christopher Markiewicz, Jessica Turner, + Vince Calhoun, Thomas Nichols, Cyril Pernet (2020). + **The genetics-BIDS extension: Easing the search for genetic data associated with human brain imaging**. + GigaScience, 9 (10). [doi:10.1093/gigascience/giaa104](https://doi.org/10.1093/gigascience/giaa104) + +### Research Resource Identifier (RRID) BIDS has also a -[Research Resource Identifier (RRID)](https://www.force11.org/group/resource-identification-initiative) -- `RRID:SCR_016124` - which you can also include in your manuscript in addition -to citing the paper. +[Research Resource Identifier (RRID)](https://www.force11.org/group/resource-identification-initiative), +which you can also include in your citations in addition to relevant publications (see above): + +- [`RRID:SCR_016124`](https://scicrunch.org/resources/Any/search?q=SCR_016124&l=SCR_016124) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index d4f9decd..d3700c73 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -6,55 +6,120 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)]. -Throughout this specification we use a list of terms. To avoid +Throughout this specification we use a list of terms and abbreviations. To avoid misunderstanding we clarify them here. -1. Dataset - a set of neuroimaging and behavioral data acquired for a purpose - of a particular study. A dataset consists of data acquired from one or more - subjects, possibly from multiple sessions. +1. **Dataset** - a set of neuroimaging and behavioral data acquired for a + purpose of a particular study. A dataset consists of data acquired from one + or more subjects, possibly from multiple sessions. -1. Subject - a person or animal participating in the study. +1. **Subject** - a person or animal participating in the study. Used + interchangeably with term **Participant**. -1. Session - a logical grouping of neuroimaging and behavioral data consistent - across subjects. Session can (but doesn't have to) be synonymous to a visit - in a longitudinal study. In general, subjects will stay in the scanner - during one session. However, for example, if a subject has to leave the - scanner room and then be re-positioned on the scanner bed, the set of MRI - acquisitions will still be considered as a session and match sessions +1. **Session** - a logical grouping of neuroimaging and behavioral data + consistent across subjects. Session can (but doesn't have to) be synonymous + to a visit in a longitudinal study. In general, subjects will stay in the + scanner during one session. However, for example, if a subject has to leave + the scanner room and then be re-positioned on the scanner bed, the set of + MRI acquisitions will still be considered as a session and match sessions acquired in other subjects. Similarly, in situations where different data types are obtained over several visits (for example fMRI on one day followed by DWI the day after) those can be grouped in one session. Defining multiple sessions is appropriate when several identical or similar data acquisitions are planned and performed on all -or most- subjects, often in the case of - some intervention between sessions (e.g., training). + some intervention between sessions (for example, training). + In the [PET](04-modality-specific-files/09-positron-emission-tomography.md) + context, a session may also indicate a group of related scans, + taken in one or more visits. -1. Data acquisition - a continuous uninterrupted block of time during which a - brain scanning instrument was acquiring data according to particular +1. **Data acquisition** - a continuous uninterrupted block of time during which + a brain scanning instrument was acquiring data according to particular scanning sequence/protocol. -1. Data type - a functional group of different types of data. In BIDS we define - eight data types: func (task based and resting state functional MRI), dwi - (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as - field maps), anat (structural imaging such as T1, T2, etc.), meg - (magnetoencephalography), eeg (electroencephalography), ieeg (intracranial - electroencephalography), beh (behavioral). - -1. Task - a set of structured activities performed by the participant. Tasks - are usually accompanied by stimuli and responses, and can greatly vary in - complexity. For the purpose of this specification we consider the so-called +1. **Data type** - a functional group of different types of data. + BIDS defines the following data types: + + 1. `func` (task based and resting state functional MRI) + 1. `dwi` (diffusion weighted imaging) + 1. `fmap` (field inhomogeneity mapping data such as field maps) + 1. `anat` (structural imaging such as T1, T2, PD, and so on) + 1. `perf` (perfusion) + 1. `meg` (magnetoencephalography) + 1. `eeg` (electroencephalography) + 1. `ieeg` (intracranial electroencephalography) + 1. `beh` (behavioral) + 1. `pet` (positron emission tomography) + + Data files are contained in a directory named for the data type. + In raw datasets, the data type directory is nested inside subject and + (optionally) session directories. + +1. **Task** - a set of structured activities performed by the participant. + Tasks are usually accompanied by stimuli and responses, and can greatly vary + in complexity. For the purpose of this specification we consider the so-called "resting state" a task. In the context of brain scanning, a task is always tied to one data acquisition. Therefore, even if during one acquisition the subject performed multiple conceptually different behaviors (with different sets of instructions) they will be considered one (combined) task. -1. Event - a stimulus or subject response recorded during a task. Each event - has an onset time and duration. Note that not all tasks will have recorded - events (e.g., resting state). - -1. Run - an uninterrupted repetition of data acquisition that has the same +1. **Event** - something that happens or may be perceived by a test subject as happening + at a particular instant during the recording. + Events are most commonly associated with on- or offset of stimulus presentations, + or with the distinct marker of on- or offset of a subject's response or motor action. + Other events may include unplanned incidents + (for example, sudden onset of noise and vibrations due to construction work, + laboratory device malfunction), + changes in task instructions (for example, switching the response hand), + or experiment control parameters (for example, + changing the stimulus presentation rate over experimental blocks), + and noted data feature occurrences (for example, a recording electrode producing noise). + In BIDS, each event has an onset time and duration. + Note that not all tasks will have recorded events (for example, "resting state"). + +1. **Run** - an uninterrupted repetition of data acquisition that has the same acquisition parameters and task (however events can change from run to run due to different subject response or randomized nature of the stimuli). Run is a synonym of a data acquisition. + Note that "uninterrupted" may look different by modality due to the nature of the + recording. + For example, in [MRI](04-modality-specific-files/01-magnetic-resonance-imaging-data.md) + or [MEG] (04-modality-specific-files/02-magnetoencephalography.md), + if a subject leaves the scanner, the acquisition must be restarted. + For some types of [PET](04-modality-specific-files/09-positron-emission-tomography.md) acquisitions, + a subject may leave and re-enter the scanner without interrupting the scan. + +1. **Modality** - the category of brain data recorded by a file. + For MRI data, different pulse sequences are considered distinct modalities, + such as `T1w`, `bold` or `dwi`. + For passive recording techniques, such as EEG, MEG or iEEG, + the technique is sufficiently uniform to define the modalities `eeg`, + `meg` and `ieeg`. + When applicable, the modality is indicated in the **suffix**. + The modality may overlap with, but should not be confused with + the **data type**. + +1. **``** - a nonnegative integer, possibly prefixed with arbitrary number of + 0s for consistent indentation, for example, it is `01` in `run-01` following + `run-` specification. + +1. **`