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..7e0291b542 --- /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@v6 + 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/schemacode_ci.yml b/.github/workflows/schemacode_ci.yml index 6cf4dbcd4c..46c437826c 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[tests] if: ${{ startsWith(github.ref, 'refs/tags/schema-') }} - name: "Build archive on tag" run: pytest tools/schemacode/bidsschematools -k make_archive @@ -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/.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 b2f40321ca..5f2ddc1b5e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,5 +1,7 @@ # 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 @@ -12,8 +14,18 @@ repos: - id: check-ast - id: check-added-large-files - id: check-case-conflict + - repo: https://github.com/python-jsonschema/check-jsonschema + rev: 0.29.1 + 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.4.0 + rev: 24.8.0 hooks: - id: black files: ^tools/(?!schemacode) @@ -33,7 +45,7 @@ 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] @@ -50,12 +62,12 @@ repos: args: [-f=standard, -c=.yamllint.yml] files: src/schema/.*/.*\.yaml - 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.9.0 + rev: v1.11.1 hooks: - id: mypy # Sync with project.optional-dependencies.typing @@ -69,5 +81,11 @@ repos: - 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 8d6c26487a..5f10c62bdf 100644 --- a/.remarkrc +++ b/.remarkrc @@ -4,7 +4,7 @@ "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], diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c34f9cb514..adae5e2cba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -202,28 +202,28 @@ 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"`) | @@ -257,6 +257,9 @@ The keyword for the heading must be one of the following: - 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/) @@ -721,17 +724,12 @@ 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`). - -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") +You can see the workflow in the following GitHub Actions configuration file: `.github/workflows/changelog_generator.yml`. -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. 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/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/Release_Protocol.md b/Release_Protocol.md index c93c039a48..9e2f6292c6 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) 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/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..106f7e1aa0 100644 --- a/src/CHANGES.md +++ b/src/CHANGES.md @@ -1,15 +1,50 @@ # Changelog +## [Unreleased](https://github.com/bids-standard/bids-specification/tree/HEAD) + +- \[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)) +- \[INFRA] Introduce metaschema [#1787](https://github.com/bids-standard/bids-specification/pull/1787) ([bendichter](https://github.com/bendichter)) +- \[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]\[SCHEMA] Allow .bval and .bvec files for pepolar fmaps [#1754](https://github.com/bids-standard/bids-specification/pull/1754) ([mattcieslak](https://github.com/mattcieslak)) +- FIX: Move `\_stim.\` specification within the Task Events module [#1750](https://github.com/bids-standard/bids-specification/pull/1750) ([oesteban](https://github.com/oesteban)) +- ENH: Add compressed TSV files to the common principles [#1749](https://github.com/bids-standard/bids-specification/pull/1749) ([oesteban](https://github.com/oesteban)) +- \[MAINT] split physio metadata tables [#1746](https://github.com/bids-standard/bids-specification/pull/1746) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[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] 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)) +- \[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)) +- \[FIX] fix typo in motion.md [#1731](https://github.com/bids-standard/bids-specification/pull/1731) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[ENH] Specify the naming of scanner-generated TRACE and ADC volumes [#1725](https://github.com/bids-standard/bids-specification/pull/1725) ([effigies](https://github.com/effigies)) +- FIX: Re-add run entity to electrodes.tsv [#1722](https://github.com/bids-standard/bids-specification/pull/1722) ([effigies](https://github.com/effigies)) +- \[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] Missing word in `genetic-descriptor.md` [#1715](https://github.com/bids-standard/bids-specification/pull/1715) ([markmikkelsen](https://github.com/markmikkelsen)) +- Add `descriptions.tsv` to the schema [#1707](https://github.com/bids-standard/bids-specification/pull/1707) ([tsalo](https://github.com/tsalo)) +- \[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)) +- 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)) +- \[STY] apply black 24.1.0 [#1688](https://github.com/bids-standard/bids-specification/pull/1688) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[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)) +- \[ENH] Add support for HiP-CT [#1686](https://github.com/bids-standard/bids-specification/pull/1686) ([balbasty](https://github.com/balbasty)) +- \[FIX] Add `part-` to the PEPOLAR fieldmaps [#1685](https://github.com/bids-standard/bids-specification/pull/1685) ([oesteban](https://github.com/oesteban)) +- \[MISC] Restructure MEG empty room example texts [#1677](https://github.com/bids-standard/bids-specification/pull/1677) ([guiomar](https://github.com/guiomar)) +- ENH: Add sample metadata to MRI and PET [#1593](https://github.com/bids-standard/bids-specification/pull/1593) ([effigies](https://github.com/effigies)) +- \[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 generic metadata from BEP22 to MRI [#1396](https://github.com/bids-standard/bids-specification/pull/1396) ([Remi-Gau](https://github.com/Remi-Gau)) +- \[FIX] Consistently refer to Neuromag/Elekta/MEGIN [#1310](https://github.com/bids-standard/bids-specification/pull/1310) ([sappelhoff](https://github.com/sappelhoff)) + ## [v1.9.0](https://github.com/bids-standard/bids-specification/tree/v1.9.0) (2023-11-20) +- \[ENH] Add `descriptions.tsv` file relating to the `desc-