diff --git a/.all-contributorsrc b/.all-contributorsrc index 7d85506d8a..9ba497aeb7 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -274,6 +274,14 @@ "name": "Anthony Galassi", "profile": "https://github.com/bendhouseart" }, + { + "contributions": [ + "doc" + ], + "login": "arianna_sala", + "name": "Arianna Sala", + "profile": "https://www.coma.uliege.be/people/arianna-sala/" + }, { "avatar_url": [ "https://avatars.githubusercontent.com/u/118582?v=4" @@ -383,10 +391,13 @@ }, { "contributions": [ - "doc" + "doc", + "code", + "test" ], "login": "benjamin_dichter", - "name": "Benjamin Dichter" + "name": "Benjamin Dichter", + "profile": "https://bendichter.com/" }, { "contributions": [ @@ -1999,11 +2010,14 @@ { "avatar_url": "https://avatars.githubusercontent.com/u/6051303?v=4", "contributions": [ - "doc" + "doc", + "code", + "data", + "review" ], "login": "markmikkelsen", "name": "Mark Mikkelsen", - "profile": "https://vivo.weill.cornell.edu/display/cwid-mam4041" + "profile": "https://mikkelsenlab.weill.cornell.edu/" }, { "contributions": [ @@ -2303,6 +2317,13 @@ "login": "nicole_c_swann", "name": "Nicole C. Swann" }, + { + "contributions": [ + "doc" + ], + "login": "nbeliy", + "name": "Nikita Beliy" + }, { "contributions": [ "doc" @@ -2636,6 +2657,13 @@ "login": "samuel_garcia", "name": "Samuel Garcia" }, + { + "contributions": [ + "doc" + ], + "login": "SamGuay", + "name": "Samuel Guay" + }, { "avatar_url": [ "https://avatars.githubusercontent.com/u/3496566?v=4" @@ -3079,6 +3107,13 @@ "login": "viacovella", "name": "Vittorio Iacovella" }, + { + "contributions": [ + "doc" + ], + "login": "viviana_siless", + "name": "Viviana Siless" + }, { "contributions": [ "doc" diff --git a/.circleci/config.yml b/.circleci/config.yml index ee82d5b003..63f1dd4ce8 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -93,112 +93,6 @@ jobs: - store_artifacts: path: bids-spec.pdf - # Automatically generate a changelog since migration from Google Docs to GitHub - github_changelog_generator: - docker: - - image: ferrarimarco/github-changelog-generator:1.14.3 - steps: - - setup_remote_docker: - version: 18.06.0-ce - # checkout code to default ~/project - - checkout - - run: - 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 \ - --exclude-tags-regex "^(?!v).*?$" \ - --user bids-standard \ - --project bids-specification \ - --token ${CHANGE_TOKEN} \ - --output ~/changelog_build/CHANGES.md \ - --base ~/project/src/pregh-changes.md \ - --header-label "# Changelog" \ - --release-branch master \ - --no-issues \ - --no-filter-by-milestone \ - --no-compare-link \ - --pr-label "" \ - --enhancement-label "" \ - --bugs-label "" \ - --exclude-labels "exclude-from-changelog" - cat ~/changelog_build/CHANGES.md - else - echo "Commit or Release, do nothing" - fi - - persist_to_workspace: - # raw generated changelog in ~/changelog_build/CHANGES.md - root: ~/. - paths: - - changelog_build - - # Lint and fix the auto generated changes.md file - lint_generated_changelog: - docker: - - image: cimg/node:lts - steps: - # checkout code to default ~/project - - checkout - - attach_workspace: - # the freshly built CHANGES.md will be in ~/changelog_build/CHANGES.md - at: ~/. - - run: - name: install remark and extensions - command: npm install `cat npm-requirements.txt` - - run: - name: remark on autogenerated CHANGES.md - # format changelog, then use sed to change * to -, then lint changelog - command: | - 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: - # linted and fixed changelog in ~/changelog_build/CHANGES.md - root: ~/. - paths: - - changelog_build - - # Push built changelog to repo - commit_generated_changelog: - docker: - - image: cimg/base:stable - steps: - - setup_remote_docker: - version: 17.11.0-ce - # checkout code to default ~/project - - checkout - - attach_workspace: - # fixed+linted changelog in ~/changelog_build/CHANGES.md - at: ~/. - - run: - 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: search_build: jobs: @@ -206,20 +100,4 @@ workflows: - check_links: requires: - build_docs - - github_changelog_generator: - filters: - branches: - only: master - - lint_generated_changelog: - requires: - - github_changelog_generator - filters: - branches: - only: master - - commit_generated_changelog: - requires: - - lint_generated_changelog - filters: - branches: - only: master - build_docs_pdf diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fa9d6566cf..b6be304f5b 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,27 +2,52 @@ 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 keep the title of your Pull Request (PR) short but informative - it will appear in the changelog. - If you do **not** want a PR to appear in the changelog, it must receive the `exclude-from-changelog` label. -- Please ensure your name is credited on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/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. + +- Please ensure your name is credited + on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/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 tag @bids-standard/maintainers. + - Use one of the following prefixes in the title of your PR: - - `[ENH]` - enhancement of the specification that adds a new feature or - support for a new data type + - `[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) + - `[INFRA]` - changes to the infrastructure automating the specification release (for example building HTML docs) - `[SCHEMA]` - changes to the BIDS schema and/or related code - - `[MISC]` - everything else including changes to the file listing - contributors -- If you are opening a PR to obtain early feedback, but the changes - are not ready to be merged (also known as a "Work in Progress" PR), please - use a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/). -- After opening the PR, our continuous integration services will automatically check your contribution for formatting errors and render a preview of the BIDS specification with your changes. + - `[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 (also known as a "Work in Progress" PR), + please use a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/). + +- After opening the PR, our continuous integration services will automatically check your contribution + for formatting errors and render a preview of the BIDS specification with your changes. To see the checks and preview, scroll down and click on the `show all checks` link. - From the list, select the `Details` link of the `ci/circleci: build_docs artifact` check to see the preview of the BIDS specification. -- If you are updating the schema *and* you need to subsequently make changes to the bidsschematools code (validation, tests, rendering), this means your PR probably introduces a compatibility breaking change and you should increment the minor version (the second number) in `bids-specification/src/schema/SCHEMA_VERSION`. + From the list: + - select the `Details` link of the `docs/readthedocs.org:bids-specification` check to see the HTML preview of the BIDS specification. + - select the `Details` link of the `Check the rendered PDF version here! ` check to see the PDF preview of the BIDS specification. + +- If you are updating the schema *and* you need to subsequently make changes to the bidsschematools code (validation, tests, rendering), + this means your PR probably introduces a compatibility breaking change + and you should increment the minor version (the second number) in `bids-specification/src/schema/SCHEMA_VERSION`. + +- If you are opening a PR for a BIDS extension proposal (BEP), + make sure that your top message contains the following notes + +> [!Note] +> +> **We meet regularly to discuss this BEP** +> +> Next meeting: **insert date** on **URL to join** +> +> Communication channel on github repo / matrix / slack / discord : **insert URL to join** +> + +> [!Tip] +> +> [**HTML preview of this BEP**](insert URL to HTML preview once available) +> --- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- diff --git a/.github/workflows/changelog_generator.yml b/.github/workflows/changelog_generator.yml new file mode 100644 index 0000000000..baa42afe83 --- /dev/null +++ b/.github/workflows/changelog_generator.yml @@ -0,0 +1,134 @@ +--- +name: GitHub_Changelog_Generator + +on: + push: + branches: ["master"] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + github_changelog_generator: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.2' + - name: Install dependencies + run: | + gem install github_changelog_generator + - name: Check version + run: | + github_changelog_generator --version + - name: Build changelog + run: | + mkdir ~/changelog_build + github_changelog_generator \ + --exclude-tags-regex "^(?!v).*?$" \ + --user bids-standard \ + --project bids-specification \ + --token ${{ secrets.GITHUB_TOKEN }} \ + --output ~/changelog_build/CHANGES.md \ + --header-label "# Changelog" \ + --release-branch master \ + --no-issues \ + --no-filter-by-milestone \ + --no-compare-link \ + --pr-label "" \ + --enhancement-label "" \ + --bugs-label "" \ + --exclude-labels "exclude-from-changelog" + - name: Append changelog from pre-GitHub times + run: | + cat ${{ github.workspace }}/src/pregh-changes.md >> ~/changelog_build/CHANGES.md + - name: Remove the inserted advert from the file + run: | + sed -i '/This Changelog was automatically generated by/d' ~/changelog_build/CHANGES.md + - name: Print out complete changelog + run: | + cat ~/changelog_build/CHANGES.md + - name: Archive changelog + uses: actions/upload-artifact@v4 + with: + name: changelog_pre_lint + path: | + ~/changelog_build/CHANGES.md + + lint_generated_changelog: + needs: github_changelog_generator + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Download previously build changelog + uses: actions/download-artifact@v4 + with: + name: changelog_pre_lint + path: ~/changelog_build + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Install remark and extensions + run: | + npm install `cat npm-requirements.txt` + - name: Remark on autogenerated CHANGES.md + # first remove empty lines + # then run remark to re-organize + # replace remark's bullet list "*" with "-" + # final run of remark to check everything passes now + run: | + head -n 25 ~/changelog_build/CHANGES.md + sed -i '/^$/d' ~/changelog_build/CHANGES.md + echo $'\n------------------------------\n' + head -n 25 ~/changelog_build/CHANGES.md + npx remark ~/changelog_build/CHANGES.md --rc-path ${{ github.workspace }}/.remarkrc --output ~/changelog_build/CHANGES.md --quiet + echo $'\n------------------------------\n' + head -n 25 ~/changelog_build/CHANGES.md + sed -i 's/^* /- /' ~/changelog_build/CHANGES.md + echo $'\n------------------------------\n' + head -n 25 ~/changelog_build/CHANGES.md + npx remark ~/changelog_build/CHANGES.md --rc-path ${{ github.workspace }}/.remarkrc --frail --quiet --no-stdout + - name: Archive linted changelog + uses: actions/upload-artifact@v4 + with: + name: changelog_post_lint + path: | + ~/changelog_build/CHANGES.md + + commit_generated_changelog: + permissions: + contents: write + pull-requests: write + needs: lint_generated_changelog + # Run only if the head commit message contains "[build changelog]"" + if: contains(github.event.head_commit.message, '[build changelog]') + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Download previously build changelog + uses: actions/download-artifact@v4 + with: + name: changelog_post_lint + path: ~/changelog_build + - name: add changelog to git + run: | + mv ~/changelog_build/CHANGES.md ${{ github.workspace }}/src/CHANGES.md + git config credential.helper 'cache --timeout=120' + git config user.email "bids.maintenance@gmail.com" + git config user.name "bids-maintenance" + git add ${{ github.workspace }}/src/CHANGES.md + git commit -m "[DOC] Auto-generated changelog entry" + - name: Create Pull Request + uses: peter-evans/create-pull-request@v7 + with: + token: ${{ secrets.GITHUB_TOKEN }} + branch: changelog_generator_update + delete-branch: true + title: '[DOC] Auto-generated changelog entry' + labels: | + exclude-from-changelog + draft: false diff --git a/.github/workflows/publish_schema.yml b/.github/workflows/publish_schema.yml new file mode 100644 index 0000000000..c2528e02c4 --- /dev/null +++ b/.github/workflows/publish_schema.yml @@ -0,0 +1,89 @@ +name: "Publish schema" + +on: + push: + branches: + - "master" + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +defaults: + run: + shell: bash + +env: + GIT_AUTHOR_NAME: BIDS CI + GIT_AUTHOR_EMAIL: bids.maintenance@gmail.com + GIT_COMMITTER_NAME: BIDS CI + GIT_COMMITTER_EMAIL: bids.maintenance@gmail.com + +permissions: + contents: write + id-token: write + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + filter: "blob:none" + - uses: actions/setup-python@v5 + with: + python-version: 3 + - name: Install bidsschematools + run: | + pip install --upgrade tools/schemacode + git clean -fxd tools/schemacode + - name: Checkout jsr-dist + run: | + git checkout -t origin/jsr-dist + - name: Regenerate schema + run: bst export > schema.json + - name: Regenerate context types + run: | + jq .meta.context schema.json \ + | npx quicktype --src-lang schema --lang ts -t Context --just-types \ + > context.ts + - name: Regenerate metaschema types + run: | + # Name the file schema so the type will be named Schema + bst export-metaschema > /tmp/schema.json + npx --package=json-schema-to-typescript json2ts --unknownAny /tmp/schema.json > metaschema.ts + - name: Determine next version + run: | + BASE=$( jq -r .schema_version schema.json ) + if [[ "$BASE" =~ ^[0-9]*.[0-9]*.[0-9]*$ ]]; then + # Release, so unconditionally update version + VERSION=$BASE + jq ".version = \"$VERSION\"" jsr.json > tmp.json && mv tmp.json jsr.json + else + DENOVER=$( jq -r .version jsr.json ) + # Get the reference of the latest commit to touch the schema directory + HASH=$( git log -n 1 --pretty=%h $REF -- src/schema ) + if [[ $DENOVER =~ ^"$BASE".[0-9] ]]; then + PREFIX=${DENOVER%+*} + let SERIAL=1+${PREFIX#$BASE.} + else + SERIAL=1 + fi + VERSION="$BASE.$SERIAL+$HASH" + fi + echo VERSION=$VERSION | tee -a $GITHUB_ENV + env: + REF: ${{ github.ref }} + - name: Check for changes, set version and commit + run: | + if ! git diff -s --exit-code; then + jq ".version = \"$VERSION\"" jsr.json > tmp.json && mv tmp.json jsr.json + git add jsr.json schema.json context.ts metaschema.ts + git commit -m "Update schema JSR distribution" + git push + fi + - name: Publish to JSR + if: success() + run: | + npx jsr publish diff --git a/.github/workflows/schemacode_ci.yml b/.github/workflows/schemacode_ci.yml index 6cf4dbcd4c..cff7d01d54 100644 --- a/.github/workflows/schemacode_ci.yml +++ b/.github/workflows/schemacode_ci.yml @@ -33,7 +33,7 @@ jobs: - name: "Install build dependencies" run: pip install --upgrade build twine - name: "Install test dependencies on tag" - run: pip install --upgrade pytest pyyaml pandas tabulate markdown-it-py pyparsing + run: pip install --upgrade tools/schemacode[all] if: ${{ startsWith(github.ref, 'refs/tags/schema-') }} - name: "Build archive on tag" run: pytest tools/schemacode/bidsschematools -k make_archive @@ -56,7 +56,7 @@ jobs: fail-fast: false matrix: os: ["ubuntu-latest"] - python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"] + python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] include: - os: macos-latest python-version: 3 @@ -117,8 +117,8 @@ jobs: with: user: __token__ password: ${{ secrets.TEST_PYPI_API_TOKEN }} - repository_url: https://test.pypi.org/legacy/ - skip_existing: true + repository-url: https://test.pypi.org/legacy/ + skip-existing: true - name: "Upload to PyPI (on tags)" if: startsWith(github.ref, 'refs/tags/schema-') uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml new file mode 100644 index 0000000000..c4e38c1d1d --- /dev/null +++ b/.github/workflows/shellcheck.yml @@ -0,0 +1,26 @@ +--- +name: Shellcheck + +on: + push: + branches: [master] + pull_request: + branches: [master] + +permissions: + contents: read + +jobs: + shellcheck: + name: Check shell scripts + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install dependencies + run: | + sudo apt update && sudo apt install -y shellcheck + - name: shellcheck + run: | + git grep -l '^#\( *shellcheck \|!\(/bin/\|/usr/bin/env \)\(sh\|bash\|dash\|ksh\)\)' | xargs shellcheck diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml index 5be42a5b18..ee554f9f59 100644 --- a/.github/workflows/validation.yml +++ b/.github/workflows/validation.yml @@ -26,7 +26,7 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 22 - name: Install dependencies run: npm install `cat npm-requirements.txt` - name: Run style checks diff --git a/.gitignore b/.gitignore index 59fa1a1de3..9e8cf66a91 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ venvs pdf_build_src/bids-spec.pdf pdf_build_src/bids-spec_pandoc_log.json pdf_build_src/src_copy +pdf_build_src/tests/data/output # JS/NPM package-lock.json diff --git a/.mailmap b/.mailmap index 066e8097c5..087f292a4f 100644 --- a/.mailmap +++ b/.mailmap @@ -64,3 +64,5 @@ Patrick Park Ezequiel Mikulan Guillaume Flandin + +Dimitri Papadopoulos Orfanos <3234522+DimitriPapadopoulos@users.noreply.github.com> diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1129a080c0..83f40fdbb4 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,19 +1,32 @@ # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks +ci: + skip: [shellcheck] exclude: 'tools/schemacode/bidsschematools/tests/data/broken_dataset_description.json' repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.5.0 + rev: v5.0.0 hooks: - id: trailing-whitespace - id: end-of-file-fixer - id: check-yaml - id: check-json + - id: check-toml - id: check-ast - id: check-added-large-files - id: check-case-conflict + - repo: https://github.com/python-jsonschema/check-jsonschema + rev: 0.29.4 + hooks: + - id: check-dependabot + - id: check-github-workflows + args: ["--verbose"] + - id: check-metaschema + files: src/metaschema.json + - id: check-readthedocs + files: readthedocs.yml - repo: https://github.com/psf/black - rev: 24.2.0 + rev: 24.10.0 hooks: - id: black files: ^tools/(?!schemacode) @@ -33,23 +46,34 @@ repos: files: tools/schemacode args: ["--settings-file", "tools/schemacode/pyproject.toml"] - repo: https://github.com/pyCQA/flake8 - rev: 7.0.0 + rev: 7.1.1 hooks: - id: flake8 - args: [--config=tools/schemacode/setup.cfg] + args: [--config=tools/schemacode/.flake8] - repo: https://github.com/pre-commit/mirrors-prettier rev: v4.0.0-alpha.8 hooks: - id: prettier entry: env PRETTIER_LEGACY_CLI=1 prettier # temporary fix for https://github.com/prettier/prettier/issues/15742 files: src/schema/.*/.*\.yaml + - repo: https://github.com/adrienverge/yamllint + rev: v1.35.1 + hooks: + - id: yamllint + args: [-f=standard, -c=.yamllint.yml] + files: src/schema/.*/.*\.yaml + - repo: https://github.com/macisamuele/language-formatters-pre-commit-hooks + rev: v2.14.0 + hooks: + - id: pretty-format-toml + args: [--autofix, --indent, '4', --no-sort] - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"] - repo: https://github.com/pre-commit/mirrors-mypy - rev: v1.8.0 + rev: v1.13.0 hooks: - id: mypy # Sync with project.optional-dependencies.typing @@ -62,5 +86,12 @@ repos: - pytest - types-PyYAML - types-tabulate + - types-jsonschema + - jsonschema + - httpx args: ["tools/schemacode/bidsschematools"] pass_filenames: false + - repo: https://github.com/koalaman/shellcheck-precommit + rev: v0.10.0 + hooks: + - id: shellcheck diff --git a/.remarkrc b/.remarkrc index fc065759c2..5f10c62bdf 100644 --- a/.remarkrc +++ b/.remarkrc @@ -4,12 +4,13 @@ "preset-lint-recommended", "remark-gfm", ["lint-no-duplicate-headings", false], - ["lint-list-item-indent", "tab-size"], + ["lint-list-item-indent", "tab"], ["lint-emphasis-marker", "consistent"], ["lint-maximum-line-length", false], ["lint-maximum-heading-length", false], ["lint-no-shortcut-reference-link", false], ["lint-no-trailing-spaces"], + ["remark-lint-code-block-style", false], ["lint-no-undefined-references", false] ] } diff --git a/.tributors b/.tributors index fa5b1a18f2..a220ce484f 100644 --- a/.tributors +++ b/.tributors @@ -244,6 +244,16 @@ "name": "Anthony Galassi", "orcid": "0000-0001-6550-4574" }, + "arianna_sala": { + "affiliation": "université de Liège, Belgium", + "blog": "https://www.coma.uliege.be/people/arianna-sala/", + "contributions": [ + "doc" + ], + "email": "arianna.sala@uliege.be", + "name": "Arianna Sala", + "orcid": "0000-0001-8121-0891" + }, "arokem": { "affiliation": "University of Washington, Psychology, Seattle, WA, 98107, United States of America", "blog": "https://arokem.org/", @@ -348,10 +358,17 @@ "publish_email": true }, "benjamin_dichter": { + "affiliation": "CatalystNeuro", + "blog": "https://bendichter.com/", "contributions": [ - "doc" + "doc", + "code", + "test" ], - "name": "Benjamin Dichter" + "email": "ben.dichter@catalystneuro.com", + "github": "bendichter", + "name": "Benjamin Dichter", + "orcid": "0000-0001-5725-6910" }, "benjamin_gagl": { "affiliation": "University of Vienna", @@ -1941,12 +1958,16 @@ "name": "Marie-Hélène Bourget" }, "markmikkelsen": { - "affiliation": "Weill Cornell Medicine, Department of Radiology, New York, NY, 10021, USA", - "blog": "https://vivo.weill.cornell.edu/display/cwid-mam4041", + "affiliation": "Weill Cornell Medicine", + "blog": "https://mikkelsenlab.weill.cornell.edu/", "contributions": [ - "doc" + "doc", + "code", + "data", + "review" ], "email": "mam4041@med.cornell.edu", + "github": "markmikkelsen", "name": "Mark Mikkelsen", "orcid": "0000-0002-0349-3782", "publish_email": true @@ -2241,6 +2262,16 @@ ], "name": "Nicole C. Swann" }, + "nbeliy": { + "affiliation": "University of Liege (Liege, Belgium)", + "contributions": [ + "doc" + ], + "email": "nikita.beliy@uliege.be", + "github": "nbeliy", + "name": "Nikita Beliy", + "orcid": "0009-0002-0830-3279" + }, "nima_bigdely_shamlo": { "contributions": [ "doc" @@ -2556,6 +2587,16 @@ ], "name": "Samuel Garcia" }, + "SamGuay": { + "affiliation": "Université de Montréal, Montreal, Québec, CA", + "contributions": [ + "doc" + ], + "email": "samuel.guay@umontreal.ca", + "github": "SamGuay", + "name": "Samuel Guay", + "orcid": "0000-0001-6990-839X" + }, "snastase": { "affiliation": "Princeton University", "blog": "https://snastase.github.io/", @@ -3005,6 +3046,14 @@ "name": "Vittorio Iacovella", "orcid": "0000-0002-0853-1573" }, + "viviana_siless": { + "affiliation": "Business School, Universidad Torcuato di Tella", + "contributions": [ + "doc" + ], + "email": "viviana.siless@utdt.edu", + "name": "Viviana Siless" + }, "vladimir_litvak": { "affiliation": "UCL Queen Square Institute of Neurology", "contributions": [ diff --git a/CITATION.cff b/CITATION.cff index 23f53ad4bd..40b6368127 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -5,9 +5,10 @@ cff-version: 1.2.0 title: The Brain Imaging Data Structure (BIDS) Specification abstract: >- - The Brain Imaging Data Structure (BIDS) is a simple and intuitive way to organize and describe data. + The Brain Imaging Data Structure (BIDS) is a simple and intuitive way to organize + and describe data. -version: 1.10.0-dev +version: 1.10.1-dev license: CC-BY-4.0 @@ -142,6 +143,12 @@ authors: family-names: Galassi website: https://github.com/bendhouseart orcid: https://orcid.org/0000-0001-6550-4574 + - given-names: Arianna + family-names: Sala + website: https://www.coma.uliege.be/people/arianna-sala/ + orcid: https://orcid.org/0000-0001-8121-0891 + affiliation: université de Liège, Belgium + email: arianna.sala@uliege.be - given-names: Ariel family-names: Rokem website: https://arokem.org/ @@ -189,6 +196,10 @@ authors: website: https://github.com/musicinmybrain - given-names: Benjamin family-names: Dichter + website: https://bendichter.com/ + orcid: https://orcid.org/0000-0001-5725-6910 + affiliation: CatalystNeuro + email: ben.dichter@catalystneuro.com - given-names: Benjamin family-names: Gagl orcid: https://orcid.org/0000-0002-2339-6293 @@ -872,10 +883,9 @@ authors: website: https://github.com/mariehbourget - given-names: Mark family-names: Mikkelsen - website: https://vivo.weill.cornell.edu/display/cwid-mam4041 + website: https://mikkelsenlab.weill.cornell.edu/ orcid: https://orcid.org/0000-0002-0349-3782 - affiliation: Weill Cornell Medicine, Department of Radiology, New York, NY, 10021, - USA + affiliation: Weill Cornell Medicine email: mam4041@med.cornell.edu - given-names: Markus family-names: Morawski @@ -993,6 +1003,11 @@ authors: family-names: Ramsey - given-names: Nicole C. family-names: Swann + - given-names: Nikita + family-names: Beliy + orcid: https://orcid.org/0009-0002-0830-3279 + affiliation: University of Liege (Liege, Belgium) + email: nikita.beliy@uliege.be - given-names: Nima family-names: Bigdely Shamlo orcid: https://orcid.org/0000-0001-6403-892X @@ -1077,7 +1092,8 @@ authors: email: Rik.Henson@mrc-cbu.cam.ac.uk - given-names: Robert B. family-names: Innis - website: https://www.nimh.nih.gov/research/research-conducted-at-nimh/research-areas/clinics-and-labs/mib/molecular-imaging-branch-mib + website: + https://www.nimh.nih.gov/research/research-conducted-at-nimh/research-areas/clinics-and-labs/mib/molecular-imaging-branch-mib orcid: https://orcid.org/0000-0003-1238-7209 affiliation: NIMH Intramural Research Program, Bethesda, MD 20850 USA, MD 20892 USA email: robert.innis@nih.gov @@ -1121,6 +1137,11 @@ authors: website: https://github.com/samirdas - given-names: Samuel family-names: Garcia + - given-names: Samuel + family-names: Guay + orcid: https://orcid.org/0000-0001-6990-839X + affiliation: Université de Montréal, Montreal, Québec, CA + email: samuel.guay@umontreal.ca - given-names: Samuel family-names: Nastase website: https://snastase.github.io/ @@ -1312,6 +1333,10 @@ authors: - given-names: Vittorio family-names: Iacovella orcid: https://orcid.org/0000-0002-0853-1573 + - given-names: Viviana + family-names: Siless + affiliation: Business School, Universidad Torcuato di Tella + email: viviana.siless@utdt.edu - given-names: Vladimir family-names: Litvak orcid: https://orcid.org/0000-0001-8535-7452 diff --git a/CODEOWNERS b/CODEOWNERS index 54d256bb49..fff5d95928 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -16,5 +16,5 @@ /src/derivatives/diffusion-derivatives.md @francopestilli @oesteban @Lestropie # The schema -/src/schema/ @tsalo @erdalkaraca -/tools/schemacode/ @tsalo @erdalkaraca +/src/schema/ @erdalkaraca +/tools/schemacode/ @erdalkaraca diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96b8a53c0a..f5d9cd972c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,10 +4,15 @@ _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. +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). +by [opening an issue](https://github.com/bids-standard/bids-specification/issues/new). + +If you are not familiar with Git ansd GitHub, +check our [generic contributing guidelines](https://bids-website.readthedocs.io/en/latest/collaboration/bids_github/CONTRIBUTING.html). + +If you want to contribute to the BIDS website, +make sure you also read the instructions below. ## Table of contents @@ -15,114 +20,6 @@ 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) -- [Using macros](#using-macros) -- [Fixing Markdown style errors](#fixing-markdown-style-errors) -- [Using pre-commit hooks](#using-pre-commit-hooks) -- [Adding a figure to the specifications](#adding-a-figure-to-the-specifications) -- [Making a change with a pull request](#making-a-change-with-a-pull-request) -- [Example pull request](#example-pull-request) -- [Commenting on a pull request](#commenting-on-a-pull-request) -- [Accepting suggestion from a review](#accepting-suggestion-from-a-review) -- [Making a change to the BIDS-schema](#making-a-change-to-the-BIDS-schema) -- [How the decision to merge a pull request is made?](#how-is-the-decision-to-merge-a-pull-request-made) -- [How is the changelog generated?](#how-is-the-changelog-generated) -- [Recognizing contributions](#recognizing-contributions) - -## Joining the community - -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! - -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. - -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). - -## 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. - -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. - -## Understanding issues - -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. - -**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. - -### Issue labels - -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/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! - -- [![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! - -- [![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 @@ -202,30 +99,64 @@ 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"`) | + +### MkDocs admonitions + +It is possible to use [Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end) +to highlight certain aspect of the specification. + +Admonitions are written like this: + +```` +!!! note "displayed heading is preceded by a keyword and 3 `!`" + + Body of the admonition + can be written on several lines, + but must be always preceded by 4 spaces. +```` + +The keyword for the heading must be one of the following: + +- note +- abstract +- info +- tip +- success +- question +- warning +- failure: octicons +- danger +- bug +- example +- quote + +Do not put [macros](#using-macros) in admonitions, +as this will likely not give the output you expect. + ## Using macros We use [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) @@ -238,7 +169,7 @@ We have dedicated documentation for this, see the [macros_doc.ms](./macros_doc.m We are using MkDocs to render our specification. Please follow these instructions if you would like to build the specification locally. -#### 1. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer +### 1. 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" @@ -250,7 +181,7 @@ Or you can use the following `git` command in a terminal: git clone https://github.com/bids-standard/bids-specification.git ``` -#### 2. In the terminal (command line) navigate to your local version of the specification +### 2. 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). @@ -265,7 +196,7 @@ cd bids-specification Enter all commands below from the command line prompt located at the root of the local version of the specification. -#### 3. Install MkDocs, the Material theme and the required extensions +### 3. Install MkDocs, the Material theme and the required extensions In the following links, you can find more information about @@ -324,7 +255,7 @@ This installs the `bidsschemacode` package in "editable" mode, so that any changes you make to the code will be reflected when you use it, such as when you build the documentation locally. -#### 4. Ready to build! +### 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. @@ -406,19 +337,6 @@ Using `remark` to fix some linting errors might introduce some additional change 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. -## Using pre-commit hooks - -> Git hook scripts are useful for identifying simple issues before submission to code review. - -For more information on Git hooks, see: https://pre-commit.com/. - -Contributors to the bids-specification repository can optionally make use of the `.pre-commit-config.yaml` -configuration file at the root of the repository. -Using Python, simply install `pre-commit` via `pip`, and then run `pre-commit install` from the root -of the bids-specification repository. - -To uninstall the pre-commit hooks, run `pre-commit uninstall`. - ## Adding a figure to the specifications > A figure is worth a 1000 words! @@ -440,6 +358,7 @@ Figures can be inserted in a Markdown like this (see also ```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) @@ -457,190 +376,6 @@ future. 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. - -#### 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. - -#### 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! - -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. - -#### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) - -Please keep the title of your pull request short but informative because it will -appear in the [changelog](src/CHANGES.md) ([see below](#how-is-the-changelog-generated)). - -Use one of the following prefixes in the title of your pull request: - -- `[ENH]` - enhancement of the specification that adds a new feature or - support for a new data type -- `[FIX]` - fix of a typo or language clarification -- `[INFRA]` - changes to the infrastructure automating the specification - release (for example building HTML docs) -- `[SCHEMA]` - changes to the BIDS schema and/or related code -- `[MISC]` - everything else including changes to the file listing - contributors - -If you are opening a 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 [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. - -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 - -## Commenting on a pull request - -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). - -![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 @@ -675,12 +410,6 @@ While the continuous integration run on pull requests by the repository will ren 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 is the decision to merge a pull request made? The decision-making rules are outlined in @@ -690,36 +419,16 @@ The decision-making rules are outlined in The changelog (see `src/CHANGES.md`) is generated automatically using [github-changelog-generator](https://github.com/github-changelog-generator/github-changelog-generator). -You can see the workflow in the CircleCI configuration file (`.circleci/config.yml`). +You can see the workflow in the following GitHub Actions configuration file: `.github/workflows/changelog_generator.yml`. -As it stands, the changelog is generated whenever a pull request is integrated into -the `master` branch of the specification via a "Merge commit" -(as opposed to "Squash and merge" or "Rebase and merge"; -see the [GitHub help page](https://help.github.com/en/articles/about-merge-methods-on-github) -for more information on merge methods). - -![merge-commit](release_images/merge_commit.png "merge-commit") - -Note that for pull requests starting with `REL:`, no changelog is generated. +This workflow is triggered for every commit to `master` that contains string `[build changelog]` in its commit message. +If you push several commits at once, you need to make sure that the "youngest commit" (the HEAD commit) contains that string. +The workflow will then open a Pull Request to incorporate the updated changelog. +Check the proposed changes and merge the Pull Request at will. To exclude pull requests from showing up in the changelog, they have to be labeled with the "exclude-from-changelog" label. -## Recognizing contributions - -BIDS follows the -[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 contributors in the -[contributors appendix](https://bids-specification.readthedocs.io/en/stable/appendices/contributors.html) -of the BIDS specification. - -If you have made any type of contributions to BIDS, -we encourage you to enter or update your information in the -[Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors) -according to the instructions listed there. - ## Thank you! You're awesome. diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index a29b4b8632..cbf7946af4 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -14,37 +14,15 @@ BIDS governance. ### Steering Group -Current and past members of the steering group can be found -[here](https://bids.neuroimaging.io/governance.html#bids-steering-group). +Current and past members of the steering group can be found in the +[BIDS governance](https://bids.neuroimaging.io/governance.html#bids-steering-group). ### Maintainers Group -| Name | Time commitment | Scope | Joined | -|---------------------------------------------------------------------------|-----------------|---------------------------------------|----------| -| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | Lead Maintainer | Mar 2020 | -| Chris Markiewicz ([@effigies](https://github.com/effigies)) | 5h/week | | Mar 2020 | -| Ross Blair ([@rwblair](https://github.com/rwblair)) | | Maintainer of the bids-validator | Mar 2020 | -| Taylor Salo ([@tsalo](https://github.com/tsalo)) | 3h/week | MRI | Sep 2020 | -| Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau)) | 3h/week | Community development, MRI | Oct 2020 | -| Anthony Galassi ([@bendhouseart](https://github.com/bendhouseart)) | 3h/week | PET, Community development | Sep 2021 | -| Eric Earl ([@ericearl](https://github.com/ericearl)) | 2h/week | | Dec 2021 | -| Christine Rogers ([@christinerogers](https://github.com/christinerogers)) | 2h/mo | Interoperability, EEG and multi-modal | Apr 2023 | -| Nell Hardcastle ([@nellh](https://github.com/nellh)) | 2h/week | | Jul 2023 | -| Kimberly Ray ([@KimberlyLRay](https://github.com/KimberlyLRay)) | 1h/week | | Nov 2022 | - -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. - -#### Past maintainers group members - -| Name | Duration | -|--------------------------------------------------------------------------------|---------------------| -| Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) | Mar 2020 - Jul 2022 | +Current and past members of the maintainers group can be found in the +[BIDS governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group), +and in the +[Maintainers Guide](Maintainers_Guide.md). ### BEP Leads Group @@ -62,8 +40,9 @@ according to the instructions listed there. ### 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). +The following groups are not described in detail. +Please learn more about these groups from the +[BIDS governance](https://bids.neuroimaging.io/governance.html). - BEP working groups - Advisory Group @@ -79,8 +58,7 @@ following rules with the intention to: - Minimize the administrative burden. - Provide a path for when consensus cannot be made. - Grow the community. -- Maximize the [bus factor](https://en.wikipedia.org/wiki/Bus_factor) of the - project. +- Maximize the [bus factor](https://en.wikipedia.org/wiki/Bus_factor) of the project. 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/). diff --git a/LICENSE b/LICENSE index d591978380..22091e01bb 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ Attribution 4.0 International -Copyright (c) 2018-2022, BIDS Contributors. +Copyright (c) 2018, BIDS Contributors. ======================================================================= diff --git a/Maintainers_Guide.md b/Maintainers_Guide.md new file mode 100644 index 0000000000..1c668ec382 --- /dev/null +++ b/Maintainers_Guide.md @@ -0,0 +1,135 @@ +# BIDS Maintainers Group Guide + +The BIDS Maintainers are a key group of members that ensure that the BIDS infrastructure is kept up. +The maintainers have wide-ranging responsibilities that enable BIDS to continue to grow and succeed. +As furthermore detailed in the [DECISION-MAKING document](DECISION-MAKING.md), +maintainers have a set of rights that go beyond those of a contributor. + +The following guide draws heavily on a related [blog post](https://matthewrocklin.com/blog/2019/05/18/maintainer) +on "The Role of a Maintainer" by Matthew Rocklin, +which is a recommended reading in conjunction with this guide. + +## Current BIDS Maintainers + +See also: [BIDS governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group) + +| Name | Time commitment | Scope | Joined | +| ------------------------------------------------------------------------- | --------------- | ------------------------------------- | -------- | +| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 1h/week | | Mar 2020 | +| Chris Markiewicz ([@effigies](https://github.com/effigies)) | 5h/week | | Mar 2020 | +| Ross Blair ([@rwblair](https://github.com/rwblair)) | | Maintainer of the bids-validator | Mar 2020 | +| Taylor Salo ([@tsalo](https://github.com/tsalo)) | 3h/week | MRI | Sep 2020 | +| Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau)) | 3h/week | Community development, MRI | Oct 2020 | +| Anthony Galassi ([@bendhouseart](https://github.com/bendhouseart)) | 3h/week | PET, Community development | Sep 2021 | +| Eric Earl ([@ericearl](https://github.com/ericearl)) | 2h/week | | Dec 2021 | +| Christine Rogers ([@christinerogers](https://github.com/christinerogers)) | 2h/month | Interoperability, EEG and multi-modal | Apr 2023 | +| Nell Hardcastle ([@nellh](https://github.com/nellh)) | 2h/week | | Jul 2023 | +| Kimberly Ray ([@KimberlyLRay](https://github.com/KimberlyLRay)) | 1h/week | | Nov 2022 | + +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. +Any number of 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. + +### Lead Maintainer + +The role of the "lead maintainer", that is, the BIDS maintainer currently representing the maintainers group, +is rotating among current maintainers. + +## Past BIDS Maintainers + +See also: [BIDS governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group) + +| Name | Duration | +| ------------------------------------------------------------------------------ | ------------------- | +| Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) | Mar 2020 - Jul 2022 | + +## Why become a maintainer? + +As a BIDS maintainer you may get the chance to: + +* Learn to work as a team +* Bring your expertise to the BIDS maintainers group and cover technical blind spots it may have +* Improving your technical writing skills (for example documentation) +* Learn to work with continuous integration and deployment +* Advise and participate in the development of BIDS extensions that are most commonly associated with a publication + +## Responsibilities + +* Maintainers need to be loosely aware of the entire project + and use their knowledge to facilitate and initiate interactions + between different nodes of the project + and determine a reasonable and timely order for features to be added and issues to be resolved. +* Maintainers direct other BIDS contributors in reviewing PRs, + writing clarifications to the specification, or other contributions. +* Maintainers ensure that all contributors maintain a friendly and welcoming tone + to encourage productive conversations. +* If no work team is suitable or available, + the final responsibility of getting the work done lies with the maintainers. +* The development of each BIDS extension proposal should be "followed" + by at least one maintainer who acts as a preferential point of contact + between the BIDS maintainers and the BEP leads. + +Apart from these abstract and general responsibilities, +maintainers within the BIDS community also need to ensure that the following tasks get done: + +* Keeping the + [Contributors wiki](https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors) + up to date and assisting new contributors with adding their credits, + and performing community inquiries to ensure contributors are credited in the + [Contributors appendix](https://bids-specification.readthedocs.io/en/stable/appendices/contributors.html) + * Deciding what constitutes a contribution worth adding to the "Contributors list" +* Preparing a monthly report to the BIDS Steering Group. + The monthly report is in the form of milestones, issues addressed, + and open issues raised in the past month and goals/plans for the next month. + The BIDS Steering Group may ask for additional information or propose a meeting to further discuss report items. + The report format and meetings are at the discretion of the BIDS Steering Group. + +Maintainers are not expected to individually be responsible for all the responsibilities listed. +Rather, the responsibilities are distributed amongst the entire group. + +## Organization + +* The group of maintainers are a group of people with the above mentioned responsibilities, + who commit to convene bi-weekly meetings to discuss the project. +* One lead maintainer represents the group to other BIDS Groups, mediates disagreement among members, + and casts deciding votes when needed (tie break). + Note that the maintainers will always strive for consensus decision making, and will try to avoid resorting to voting. + * The lead maintainer may delegate any of their duties to another maintainer. + * The lead maintainer is appointed collectively by the group of maintainers, preferably through consensus. + * If no one else does, the lead maintainer sets the schedule for the maintainers meeting. +* Additions to and departures from the group are negotiated collectively between the lead maintainer + and the new/departing members, as they involve the redistribution of duties. + * If a maintainer wishes to serve for a limited term, that can be arranged at the start. Otherwise, due notice is expected. + * See also "How to become a maintainer?" below + +## How to become a maintainer? + +If you are interested in becoming a BIDS maintainer, +please get in contact with an active BIDS maintainer +(for example via opening a GitHub issue on bids-standard/bids-specification and tagging `@bids-standard/maintainers`). +In that initial contact, it would be great if you could outline previous experience with BIDS (if any) +and your motivation to become a maintainer, as well as particular interests for work that you would like to do. +The BIDS maintainers will then invite you to one of the biweekly maintainers meetings (online) +to discuss further steps and point you to the onboarding documentation (things to do). + +We would be happy to hear from you! + +## Crediting BIDS maintainers in work submissions + +If you prepare a submission of work related to BIDS, and would like to credit the BIDS maintainers +in that submission, please get in touch. + +It is for example possible to include BIDS maintainers as a consortium author, +through using the following OSF account: [https://osf.io/y48x9/](https://osf.io/y48x9/) + +We are furthermore preparing more guidelines on this topic, see this work in progress: +https://docs.google.com/document/d/1yQdYOw7WMpkcFgT4tNalOjKuH34nhmRqg4luI4V9uhE/ + +## Notes + +As detailed in the [BIDS governance](https://bids.neuroimaging.io/governance.html), +this guide is subject to change and to amendment by the BIDS Steering Group. diff --git a/README.md b/README.md index 574659f292..40c29b6b81 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Validation](https://github.com/bids-standard/bids-specification/actions/workflows/validation.yml/badge.svg)](https://github.com/bids-standard/bids-specification/actions/workflows/validation.yml) [![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=shield)](https://circleci.com/gh/bids-standard/bids-specification) [![Mastodon Follow](https://img.shields.io/mastodon/follow/109520103085644521?domain=https%3A%2F%2Ffosstodon.org%2F)](https://fosstodon.org/@bidsstandard) -[![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard) +[![@BIDSstandard](https://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://x.com/BIDSstandard) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3686061.svg)](https://doi.org/10.5281/zenodo.3686061) bids-logo @@ -13,7 +13,6 @@ organization of neuroimaging data. In this repository, we develop the [BIDS specification](https://bids-specification.readthedocs.io/en/latest/). - # When to use BIDS To organize your data in BIDS, all you need is neuro data, a computer, and the @@ -31,6 +30,7 @@ BIDS currently supports the following data modalities with more to come in the f - microscopy - NIRS - motion +- MRS # Formatting your data with BIDS @@ -44,10 +44,7 @@ The specification is provided in the form of a webpage, built using 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 + - see: [BIDS communication channels](#bids-communication-channels) # Contributing to BIDS @@ -58,11 +55,34 @@ For a current list of our contributors, please see our [Contributors appendix](h When you're ready to get started, check out [our contributing guidelines](https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md). -We ask that all contributions to BIDS across all project-related spaces (including but not limited to: -[GitHub](https://github.com/bids-standard), -the [Google group](https://groups.google.com/forum/#!forum/bids-discussion), and newsletter emails), +We ask that all contributions to BIDS across all project-related spaces +(including but not limited to: +[GitHub](https://github.com/bids-standard), and the +[Google group](https://groups.google.com/forum/#!forum/bids-discussion); see +[BIDS communication channels](#bids-communication-channels)) adhere to our [code of conduct](https://github.com/bids-standard/bids-specification/blob/master/CODE_OF_CONDUCT.md). +# BIDS communication channels + +## Main communication channels + + - "Issue" pages on the different GitHub repositories of the [`bids-standard` GitHub organization](https://github.com/bids-standard), + such as the [BIDS specification repository](https://github.com/bids-standard/bids-specification/issues), + for reporting problems or making suggestions + - The [NeuroStars Discourse forum](https://neurostars.org/tags/bids), for asking usage questions + - 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 and announcements surrounding BIDS + - The [BIDS website "news"](https://bids.neuroimaging.io/news.html), similar to the Google group, for broader discussions and announcements + +## Social media channels + +- [X](https://x.com/BIDSstandard) +- [Mastodon](https://fosstodon.org/@bidsstandard) +- [Bluesky](https://bsky.app/profile/bidsstandard.bsky.social) +- [Youtube](https://www.youtube.com/channel/UCxZUcYfd_nvIVWAbzRB1tlw) +- [Instagram](https://www.instagram.com/bidsstandard/) + ## Contributors Thanks goes to these wonderful people. diff --git a/Release_Protocol.md b/Release_Protocol.md index f3163cf403..c520fec053 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -12,10 +12,6 @@ your fork locally to a directory called `bids-specification`. Before you start a release, you have to ensure that the automatically generated changelog is **up to date**. See the relevant [section in CONTRIBUTING.md](CONTRIBUTING.md#how-is-the-changelog-generated) for further information. -In practice this means ensuring that the most recently merged pull request -was merged into the `master` branch using the "Merge commit" option. - -![merge-commit](release_images/merge_commit.png.png "merge-commit") ### 1. Fetch the latest version of the [master branch of the BIDS-specification](https://github.com/bids-standard/bids-specification/tree/master) @@ -271,12 +267,16 @@ Similarly update the version in CITATION.cff with a `dev` suffix. Update the following files in the BIDS website repository (https://github.com/bids-standard/bids-website) if applicable: -- `tools/timeline.csv` -- `_data/beps.yml` -- `_data/beps_completed.yml` -- `_data/beps_other.yml` +- `data/timeline.csv` +- `data/beps/beps.yml` +- `data/beps/beps_completed.yml` +- `data/beps/beps_other.yml` + +If the release relates to the merge of a BEP, add the BEP leads to the BIDS advisory group: + +- `data/people/advisory.yml` ### 12. 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 share news of the release on the [identified platforms](https://github.com/bids-standard/bids-specification?tab=readme-ov-file#BIDS-communication-channels). Please use our previous release posts as a guide. diff --git a/macros_doc.md b/macros_doc.md index 6ec9fcf5a2..82c40dfff0 100644 --- a/macros_doc.md +++ b/macros_doc.md @@ -1,3 +1,7 @@ +--- +render_macros: false +--- + # Using MkDocs macros in the BIDS specification We use [mkdocs-macros](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) @@ -9,23 +13,6 @@ in the specification. Below you will find answers to frequently asked questions regarding using macros in the BIDS specification. -- [Using MkDocs macros in the BIDS specification](#using-mkdocs-macros-in-the-bids-specification) - - [What are macros and why use them?](#what-are-macros-and-why-use-them) - - [What kind of input information are required by macros?](#what-kind-of-input-information-are-required-by-macros) - - [What macros are available?](#what-macros-are-available) - - [When should I use a macro?](#when-should-i-use-a-macro) - - [Do I need learn how to program to use those macros?](#do-i-need-learn-how-to-program-to-use-those-macros) - - [Anything else I need to know if I need to insert a new macro call?](#anything-else-i-need-to-know-if-i-need-to-insert-a-new-macro-call) - - [How-To and Examples](#how-to-and-examples) - - [Writing directory content examples](#writing-directory-content-examples) - - [Generating tables](#generating-tables) - - [Modifying a term in the table](#modifying-a-term-in-the-table) - - [Why would you NOT want to modify the content of the yml file directly ?](#why-would-you-not-want-to-modify-the-content-of-the-yml-file-directly-) - - [Adding a new term to the table](#adding-a-new-term-to-the-table) - - [Should I create a macro if I need a new kind of table?](#should-i-create-a-macro-if-i-need-a-new-kind-of-table) - - [Why use macros at all?](#why-use-macros-at-all) - - [Links and references](#links-and-references) - ## What are macros and why use them? A macro is a rule or pattern that specifies how an input should be mapped to @@ -127,9 +114,6 @@ when you get back to the document you just edited) is to leave a comment before the macro to quickly explain what it does and where to find more information about it. - - It could for example look like this: ```markdown diff --git a/mkdocs.yml b/mkdocs.yml index 339a3d5a57..60f1aca6cb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Brain Imaging Data Structure 1.10.0-dev +site_name: Brain Imaging Data Structure 1.10.1-dev site_url: https://bids-specification.readthedocs.io/en/stable/ repo_url: https://github.com/bids-standard/bids-specification nav: @@ -12,13 +12,14 @@ nav: - Electroencephalography: modality-specific-files/electroencephalography.md - Intracranial Electroencephalography: modality-specific-files/intracranial-electroencephalography.md - Task events: modality-specific-files/task-events.md - - Physiological and other continuous recordings: modality-specific-files/physiological-and-other-continuous-recordings.md + - Physiological recordings: modality-specific-files/physiological-recordings.md - Behavioral experiments (with no neural recordings): modality-specific-files/behavioral-experiments.md - Genetic Descriptor: modality-specific-files/genetic-descriptor.md - Positron Emission Tomography: modality-specific-files/positron-emission-tomography.md - Microscopy: modality-specific-files/microscopy.md - Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md - Motion: modality-specific-files/motion.md + - Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.md - Derivatives: - BIDS Derivatives: derivatives/introduction.md - Common data types and metadata: derivatives/common-data-types.md @@ -85,12 +86,19 @@ extra: social: - icon: fontawesome/brands/github link: https://github.com/bids-standard/bids-specification/ - - icon: fontawesome/brands/twitter - link: https://twitter.com/BIDSstandard/ + - icon: fontawesome/brands/x-twitter + link: https://x.com/BIDSstandard/ - icon: fontawesome/brands/mastodon link: https://fosstodon.org/@bidsstandard - icon: fontawesome/brands/google link: https://groups.google.com/g/bids-discussion + - icon: fontawesome/brands/instagram + link: https://www.instagram.com/bidsstandard/ + - icon: fontawesome/brands/youtube + link: https://www.youtube.com/channel/UCxZUcYfd_nvIVWAbzRB1tlw + analytics: + provider: google + property: G-SBWH6YNMPX extra_javascript: - js/jquery-3.6.0.min.js @@ -98,6 +106,8 @@ markdown_extensions: - toc: anchorlink: true - pymdownx.superfences + - admonition + - pymdownx.details plugins: - search - branchcustomization: @@ -117,7 +127,7 @@ plugins: "04-modality-specific-files/03-electroencephalography.md": "modality-specific-files/electroencephalography.md" "04-modality-specific-files/04-intracranial-electroencephalography.md": "modality-specific-files/intracranial-electroencephalography.md" "04-modality-specific-files/05-task-events.md": "modality-specific-files/task-events.md" - "04-modality-specific-files/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-and-other-continuous-recordings.md" + "04-modality-specific-files/06-physiological-and-other-continuous-recordings.md": "modality-specific-files/physiological-recordings.md" "04-modality-specific-files/07-behavioral-experiments.md": "modality-specific-files/behavioral-experiments.md" "04-modality-specific-files/08-genetic-descriptor.md": "modality-specific-files/genetic-descriptor.md" "04-modality-specific-files/09-positron-emission-tomography.md": "modality-specific-files/positron-emission-tomography.md" diff --git a/npm-requirements.txt b/npm-requirements.txt index 7ef67d23b8..c2eaebe9b7 100644 --- a/npm-requirements.txt +++ b/npm-requirements.txt @@ -1,5 +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-cli@12 +remark-gfm@4 +remark-preset-lint-recommended@7 +remark-preset-lint-markdown-style-guide@6 remark-lint-no-trailing-spaces@2 diff --git a/pdf_build_src/pandoc_script.py b/pdf_build_src/pandoc_script.py index b7b1842b96..e9710482ab 100644 --- a/pdf_build_src/pandoc_script.py +++ b/pdf_build_src/pandoc_script.py @@ -2,6 +2,7 @@ This is done once the duplicate src directory is processed. """ + import subprocess import yaml from pathlib import Path @@ -11,9 +12,7 @@ def _find(path, filename): return next( - parent / filename - for parent in path.parents - if Path.is_file(parent / filename) + parent / filename for parent in path.parents if Path.is_file(parent / filename) ) diff --git a/pdf_build_src/process_markdowns.py b/pdf_build_src/process_markdowns.py index 5d30aabc21..42e984fa98 100644 --- a/pdf_build_src/process_markdowns.py +++ b/pdf_build_src/process_markdowns.py @@ -17,6 +17,8 @@ import numpy as np +from remove_admonitions import remove_admonitions + sys.path.append("../tools/") # functions from module macros are called by eval() later on from mkdocs_macros_bids import macros # noqa: F401 @@ -557,7 +559,7 @@ def correct_tables(root_path, debug=False): for i, new_line in enumerate(content): if i == start_line: new_content.pop() - if i >= start_line and i < end_line: + if start_line <= i < end_line: new_content.append("|".join(table[count]) + " \n") count += 1 elif i == end_line: @@ -585,9 +587,9 @@ def edit_titlepage(): data = file.readlines() data[-1] = ( - fr"\textsc{{\large {version_number}}}" + rf"\textsc{{\large {version_number}}}" r"\\[0.5cm]" - fr"{{\large {build_date}}}" + rf"{{\large {build_date}}}" r"\\[2cm]" r"\vfill" r"\end{titlepage}" @@ -679,33 +681,38 @@ def process_macros(duplicated_src_dir_path): duplicated_src_dir_path = "src_copy/src" - # Step 1: make a copy of the src directory in the current directory + # make a copy of the src directory in the current directory copy_src() - # Step 2: run mkdocs macros embedded in markdown files + # 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 + # remove mkdocs admonition + remove_admonitions( + input_folder=duplicated_src_dir_path, output_folder=duplicated_src_dir_path + ) + + # 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 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 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 + # modify changelog to be a level 1 heading to facilitate section # separation modify_changelog() - # Step 7: remove all internal links + # remove all internal links assert_no_multiline_links(duplicated_src_dir_path) remove_internal_links_inline(duplicated_src_dir_path) remove_internal_links_reference(duplicated_src_dir_path) - # Step 8: correct number of dashes and fences alignment for rendering tables in PDF + # correct number of dashes and fences alignment for rendering tables in PDF correct_tables(duplicated_src_dir_path) diff --git a/pdf_build_src/remove_admonitions.py b/pdf_build_src/remove_admonitions.py new file mode 100644 index 0000000000..1942f8b5b0 --- /dev/null +++ b/pdf_build_src/remove_admonitions.py @@ -0,0 +1,64 @@ +"""Script to remove all mkdocs admonition from the markdown files in a directory. + +See the pdf_build_src/tests/data/input directory to see what admonitions look like. +""" + +from __future__ import annotations + +import shutil +from pathlib import Path + +INDENT = " " + +ADMONITION_DELIMITERS = ["!!!", "???", "???+"] + + +def remove_admonitions( + input_folder: str | Path, output_folder: str | Path, indent: str = None +): + + if indent is None: + indent = INDENT + + md_files = Path(input_folder).glob("**/*.md") + + for file in md_files: + + with open(file, "r", encoding="utf8") as f: + content = f.readlines() + + output_file = Path(output_folder) / file.relative_to(input_folder) + output_file.parent.mkdir(parents=True, exist_ok=True) + print(f"processing: {file}\n to: {output_file}") + + with open(output_file, "w", encoding="utf8") as f: + + is_admonition = False + counter = 0 + for line in content: + + if any(line.startswith(x) for x in ADMONITION_DELIMITERS): + is_admonition = True + counter = 0 + continue + + # skip first line after admonition + if is_admonition and counter == 0: + counter += 1 + continue + + if line != "\n" and not line.startswith(indent): + is_admonition = False + + if is_admonition: + line = line.lstrip(indent) + + f.write(line) + + +if __name__ == "__main__": + """If run as a script this will just run the main function on test data.""" + input_folder = Path(__file__).parent / "tests" / "data" / "input" + output_folder = Path(__file__).parent / "tests" / "data" / "output" + shutil.rmtree(output_folder) + remove_admonitions(input_folder, output_folder) diff --git a/pdf_build_src/test_remove_admonitions.py b/pdf_build_src/test_remove_admonitions.py new file mode 100644 index 0000000000..e995e42246 --- /dev/null +++ b/pdf_build_src/test_remove_admonitions.py @@ -0,0 +1,25 @@ +from pathlib import Path + +from remove_admonitions import remove_admonitions + + +def test_remove_admonitions(tmp_path): + input_folder = Path(__file__).parent / "tests" / "data" / "input" + expected_folder = Path(__file__).parent / "tests" / "data" / "expected" + + remove_admonitions(input_folder, tmp_path) + + generated_files = list(tmp_path.glob("**/*.md")) + + for file in generated_files: + + expected = expected_folder / file.relative_to(tmp_path) + + with open(expected, "r", encoding="utf8") as f: + expected_content = f.readlines() + + with open(file, "r", encoding="utf8") as f: + generated_content = f.readlines() + + for expected_line, generated_line in zip(expected_content, generated_content): + assert generated_line == expected_line diff --git a/pdf_build_src/tests/data/expected/README.md b/pdf_build_src/tests/data/expected/README.md new file mode 100644 index 0000000000..37fadc295d --- /dev/null +++ b/pdf_build_src/tests/data/expected/README.md @@ -0,0 +1,32 @@ +# Test inputs + +This input directory contains data to use for testing the pdf build code of the BIDS specification. + +For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`. + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nulla et euismod nulla. +Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, +nec semper lorem quam in massa. + +The `expected` directory should contain the documents +as they should look like after processing. + +[Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end) +come in different type. In aaddtion of the classical admonitions show above you have also: + +Collapsible admonitions start with 3 questions marks (`???`). + +Collapsible admonitions that will be shown as expanded +start with 3 questions marks and a plus sign (`???+`). + + + +Let's see + +- [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb) +- foo bar [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb) + +More of the admonition + +And here we resume normal thing. diff --git a/pdf_build_src/tests/data/expected/modality-specific-files/magnetic-resonance-imaging-data.md b/pdf_build_src/tests/data/expected/modality-specific-files/magnetic-resonance-imaging-data.md new file mode 100644 index 0000000000..d70af64a49 --- /dev/null +++ b/pdf_build_src/tests/data/expected/modality-specific-files/magnetic-resonance-imaging-data.md @@ -0,0 +1,8 @@ +# Magnetic Resonance Imaging + +## Common metadata fields + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. +Nulla et euismod nulla. +Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, +nec semper lorem quam in massa. diff --git a/pdf_build_src/tests/data/input/README.md b/pdf_build_src/tests/data/input/README.md new file mode 100644 index 0000000000..cab4817282 --- /dev/null +++ b/pdf_build_src/tests/data/input/README.md @@ -0,0 +1,40 @@ +# Test inputs + +This input directory contains data to use for testing the pdf build code of the BIDS specification. + +For example the following admonition should be removed by `pdf_build_src/remove_admonitions.py`. + +!!! note + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nulla et euismod nulla. + Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, + nec semper lorem quam in massa. + +The `expected` directory should contain the documents +as they should look like after processing. + +[Mkdocs admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#inline-blocks-inline-end) +come in different type. In aaddtion of the classical admonitions show above you have also: + +??? note "Collapsible admonitions" + + Collapsible admonitions start with 3 questions marks (`???`). + +???+ note "Expanded collapsible admonitions" + + Collapsible admonitions that will be shown as expanded + start with 3 questions marks and a plus sign (`???+`). + + + +!!! example "non ordered list should be handle propeler" + + Let's see + + - [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb) + - foo bar [`UK biobank`](https://github.com/bids-standard/bids-examples/tree/master/genetics_ukbb) + + More of the admonition + +And here we resume normal thing. diff --git a/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md b/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md new file mode 100644 index 0000000000..bfc1b8509a --- /dev/null +++ b/pdf_build_src/tests/data/input/modality-specific-files/magnetic-resonance-imaging-data.md @@ -0,0 +1,10 @@ +# Magnetic Resonance Imaging + +## Common metadata fields + +!!! warning "foo bar" + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. + Nulla et euismod nulla. + Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, + nec semper lorem quam in massa. diff --git a/readthedocs.yml b/readthedocs.yml index cc3f461fc7..5611c59505 100644 --- a/readthedocs.yml +++ b/readthedocs.yml @@ -2,11 +2,14 @@ version: 2 build: os: ubuntu-22.04 + apt_packages: + - jq tools: python: "3.11" jobs: pre_build: - bst -v export --output src/schema.json + - tools/no-bad-schema-paths.sh src/schema.json # README.md might need fixing mkdocs: configuration: mkdocs.yml diff --git a/requirements.txt b/requirements.txt index 25f0520a6a..81609f6b67 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,4 @@ -mkdocs>=1.1 +mkdocs>=1.1.0 mkdocs-material>=5.4 pymdown-extensions>=7.0.0 mkdocs-branchcustomization-plugin~=0.1.3 diff --git a/scripts/test_tag b/scripts/test_tag index f11ef697dd..64e0ddd20f 100755 --- a/scripts/test_tag +++ b/scripts/test_tag @@ -9,7 +9,7 @@ EPOCH="$(date +%s)" GIT_DIR=$( git rev-parse --git-dir ) -REPO_ROOT=$( ls -d ${GIT_DIR%.git} ) +REPO_ROOT=$( ls -d "${GIT_DIR%.git}" ) VERSION_FILE="$REPO_ROOT/src/schema/SCHEMA_VERSION" diff --git a/src/CHANGES.md b/src/CHANGES.md index 087368ffea..6350df47e8 100644 --- a/src/CHANGES.md +++ b/src/CHANGES.md @@ -1,15 +1,58 @@ # Changelog -## [v1.9.0](https://github.com/bids-standard/bids-specification/tree/v1.9.0) (2023-11-20) - +## [v1.10.0](https://bids-specification.readthedocs.io/en/v1.10.0/) (2024-09-06) + +- \[ENH] Add noRF and n/a ASL volume types [1884](https://github.com/bids-standard/bids-specification/pull/1884) ([tsalo](https://github.com/tsalo)) +- \[ENH] Provide baseline definition for behavioral files [1907](https://github.com/bids-standard/bids-specification/pull/1907) ([effigies](https://github.com/effigies)) +- \[ENH] Add metadata fields for DeIdentificationMethod/CodeSequence for MRI and PET [1772](https://github.com/bids-standard/bids-specification/pull/1772) ([CGSchwarzMayo](https://github.com/CGSchwarzMayo)) +- \[ENH] Apply derivative definition to qMRI appendix [1813](https://github.com/bids-standard/bids-specification/pull/1813) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[ENH] BEP022 - Magnetic Resonance Spectroscopy [1377](https://github.com/bids-standard/bids-specification/pull/1377) ([markmikkelsen](https://github.com/markmikkelsen)) +- \[ENH] MRI: Improve definition of bvec file [1811](https://github.com/bids-standard/bids-specification/pull/1811) ([Lestropie](https://github.com/Lestropie)) +- \[ENH] Add TablePosition tag to MRI [1690](https://github.com/bids-standard/bids-specification/pull/1690) ([po09i](https://github.com/po09i)) +- \[ENH] Add explicit wording on DICOM terms correspondence [1450](https://github.com/bids-standard/bids-specification/pull/1450) ([yarikoptic](https://github.com/yarikoptic)) +- \[ENH] Generalize Units definition to apply to any variable, including TSV columns [1849](https://github.com/bids-standard/bids-specification/pull/1849) ([yarikoptic](https://github.com/yarikoptic)) +- \[ENH] Add use of session entity as example of encoding multi-site studies in a single dataset [1803](https://github.com/bids-standard/bids-specification/pull/1803) ([yarikoptic](https://github.com/yarikoptic)) +- \[ENH] Describe Inheritance Principle in Common Principles [1807](https://github.com/bids-standard/bids-specification/pull/1807) ([Lestropie](https://github.com/Lestropie)) +- \[ENH] Use deidentification consistently in place of anonymization [1799](https://github.com/bids-standard/bids-specification/pull/1799) ([DimitriPapadopoulos](https://github.com/DimitriPapadopoulos)) +- \[ENH] Allow .bval and .bvec files for pepolar fmaps [1754](https://github.com/bids-standard/bids-specification/pull/1754) ([mattcieslak](https://github.com/mattcieslak)) +- \[ENH] Add noRF suffix for MR excitation-free noise scans [1451](https://github.com/bids-standard/bids-specification/pull/1451) ([tsalo](https://github.com/tsalo)) +- \[ENH] Add warning about deidentification when sharing sourcedata [1769](https://github.com/bids-standard/bids-specification/pull/1769) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[ENH] Use "Tag XXXX, YYYY" not "Tag (XXXX,YYYY)" for DICOM Tags [1758](https://github.com/bids-standard/bids-specification/pull/1758) ([yarikoptic](https://github.com/yarikoptic)) +- \[ENH] Add generic metadata from BEP22 to MRI [1396](https://github.com/bids-standard/bids-specification/pull/1396) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[ENH] events.tsv should be sorted by onset values [1732](https://github.com/bids-standard/bids-specification/pull/1732) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[ENH] Add compressed TSV files to the common principles [1749](https://github.com/bids-standard/bids-specification/pull/1749) ([oesteban](https://github.com/oesteban)) +- \[ENH] Add support for HiP-CT [1686](https://github.com/bids-standard/bids-specification/pull/1686) ([balbasty](https://github.com/balbasty)) +- \[ENH] Add sample metadata to MRI and PET [1593](https://github.com/bids-standard/bids-specification/pull/1593) ([effigies](https://github.com/effigies)) +- \[ENH] Clarify the relation of motion.tsv columns to channels.tsv rows [1699](https://github.com/bids-standard/bids-specification/pull/1699) ([effigies](https://github.com/effigies)) +- \[ENH] Describe parametric images above the suffix table, rather than below [1687](https://github.com/bids-standard/bids-specification/pull/1687) ([CPernet](https://github.com/CPernet)) +- \[FIX] Define a metadata table for TB1EPI [1912](https://github.com/bids-standard/bids-specification/pull/1912) ([effigies](https://github.com/effigies)) +- \[FIX] Update text to reflect that BackgroundSuppressionPulseTime is recommended [1891](https://github.com/bids-standard/bids-specification/pull/1891) ([michaelf500](https://github.com/michaelf500)) +- \[FIX] Remove extra bracket [1865](https://github.com/bids-standard/bids-specification/pull/1865) ([kabilar](https://github.com/kabilar)) +- \[FIX] Change hipCT microscopy suffix to XPCT [1822](https://github.com/bids-standard/bids-specification/pull/1822) ([chourroutm](https://github.com/chourroutm)) +- \[FIX] Consistently refer to Neuromag/Elekta/MEGIN [1310](https://github.com/bids-standard/bids-specification/pull/1310) ([sappelhoff](https://github.com/sappelhoff)) +- \[FIX] Re-add run entity to electrodes.tsv [1722](https://github.com/bids-standard/bids-specification/pull/1722) ([effigies](https://github.com/effigies)) +- \[FIX] Move `rawdata/` into `sourcedata/raw` in alternative structure example, clarify on naming of datasets themselves [1741](https://github.com/bids-standard/bids-specification/pull/1741) ([yarikoptic](https://github.com/yarikoptic)) +- \[FIX] Move ``_stim.`` specification within the Task Events module [1750](https://github.com/bids-standard/bids-specification/pull/1750) ([oesteban](https://github.com/oesteban)) +- \[FIX] Remove mentions of sourcedata in the datatype specific pages [1737](https://github.com/bids-standard/bids-specification/pull/1737) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[FIX] Add misssing files in filename template for NIRS [1716](https://github.com/bids-standard/bids-specification/pull/1716) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[FIX] Remove task entity from DWI and PERF time series file templates [1703](https://github.com/bids-standard/bids-specification/pull/1703) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[FIX] Add `part-` to the PEPOLAR fieldmaps [1685](https://github.com/bids-standard/bids-specification/pull/1685) ([oesteban](https://github.com/oesteban)) +- \[INFRA] Publish schema to Javascript Registry (https://jsr.io/@bids/schema) on changes and releases [1899](https://github.com/bids-standard/bids-specification/pull/1899) ([effigies](https://github.com/effigies)) +- \[INFRA] Introduce metaschema [1787](https://github.com/bids-standard/bids-specification/pull/1787) ([bendichter](https://github.com/bendichter)) +- \[MISC] Restructure MEG empty room example texts [1677](https://github.com/bids-standard/bids-specification/pull/1677) ([guiomar](https://github.com/guiomar)) + +## [v1.9.0](https://bids-specification.readthedocs.io/en/v1.9.0/) (2023-11-20) + +- \[ENH] Add `descriptions.tsv` file relating to the `desc-