From e28a9738dbd0923272992ac305fb202edbbeca3c Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Wed, 13 Mar 2019 08:33:11 -0700 Subject: [PATCH 01/10] Adding rules about maintainers --- DECISION-MAKING.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 51aebda63c..9cc1684a85 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -25,6 +25,15 @@ community decides on the content of this file using the same process as any other change to the Repository (see below) allowing the meaning of "Contributor" to evolve independently of the Decision-making rules. +**Maintainer** - a Contributor responsible for the long term health of the +project and the community. Maintainers have additional rights (see Rules) +helping them to resolve conflicts and increase the pace of the development +when necessary. Current Maintainers: + +| Name | Time commitment | +|------|-----------------| +| Stefan Appelhoff (@sappelhoff) | 5h/week | + ## Rules 1. Every modification of the specification (including a correction of a typo, @@ -45,6 +54,10 @@ to evolve independently of the Decision-making rules. 1. Does not feature any [Reviews that Request changes](https://help.github.com/articles/about-required-reviews-for-pull-requests/). 1. Does not feature "WIP" in the title (Work in Progress). 1. Passes all automated tests. + 1. Is not proposing a new release or has been approved by at least one + Maintainer. +1. A Maintainer can merge any PR - even if it's not eligible to merge according + to Rule 4. 1. Any Contributor can Review a PR and Request changes. If a Contributor Request changes they need to provide an explanation what changes should be added and justification of their importance. Reviews requesting @@ -54,7 +67,7 @@ to evolve independently of the Decision-making rules. 1. If the author of a PR and Contributor who provided Review that Requests changes cannot find a solution that would lead to the Contributor dismissing their review or accepting the changes the Review can be Dismissed with a - vote. Rules governing voting: + vote or by a Maintainer. Rules governing voting: 1. A Vote can be triggered by any Contributor, but only after 5 working days from the time a Review Requesting Changes has been raised and in case a Vote has been triggered previously no sooner than 15 working days since @@ -70,6 +83,9 @@ to evolve independently of the Decision-making rules. ## Comments +1. Researchers preparing academic manuscripts describing work that has been + merged into this repository are strongly encouraged to invite all + Maintainers as co-authors as a form of appreciation for their work. 1. There are no restrictions on how the content of the PR is prepared. For example it is perfectly fine for a PR to consist of content developed by a group of experts over an extended period of time via in person meetings and From fd449379a38fb7eb16907e8a41b690d6a17576aa Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Wed, 13 Mar 2019 08:35:48 -0700 Subject: [PATCH 02/10] fix a table --- DECISION-MAKING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 9cc1684a85..491f80826b 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -30,9 +30,9 @@ project and the community. Maintainers have additional rights (see Rules) helping them to resolve conflicts and increase the pace of the development when necessary. Current Maintainers: -| Name | Time commitment | -|------|-----------------| -| Stefan Appelhoff (@sappelhoff) | 5h/week | +| Name | Time commitment | +|--------------------------------|-----------------| +| Stefan Appelhoff (@sappelhoff) | 5h/week | ## Rules From 9d84e38b34f4ca2ea33a7adbc29dd7f86922d634 Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Wed, 13 Mar 2019 09:36:32 -0700 Subject: [PATCH 03/10] added a link and a clarification --- DECISION-MAKING.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 491f80826b..a83dc08e1d 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -30,9 +30,9 @@ project and the community. Maintainers have additional rights (see Rules) helping them to resolve conflicts and increase the pace of the development when necessary. Current Maintainers: -| Name | Time commitment | -|--------------------------------|-----------------| -| Stefan Appelhoff (@sappelhoff) | 5h/week | +| Name | Time commitment | +|-----------------------------------------------------------------|-----------------| +| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | ## Rules @@ -55,7 +55,8 @@ when necessary. Current Maintainers: 1. Does not feature "WIP" in the title (Work in Progress). 1. Passes all automated tests. 1. Is not proposing a new release or has been approved by at least one - Maintainer. + Maintainer (i.e., PRs proposing new releases need to be approved by at + least one Maintainer). 1. A Maintainer can merge any PR - even if it's not eligible to merge according to Rule 4. 1. Any Contributor can Review a PR and Request changes. If a Contributor From 9c2f74f73f797375645182e6c20231686d286ca8 Mon Sep 17 00:00:00 2001 From: Changelog-bot Date: Tue, 19 Mar 2019 19:37:29 +0000 Subject: [PATCH 04/10] [DOC] Auto-generate changelog entry for PR #176 --- src/CHANGES.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/CHANGES.md b/src/CHANGES.md index 28e291f1a4..71f33b35b3 100644 --- a/src/CHANGES.md +++ b/src/CHANGES.md @@ -2,6 +2,7 @@ Changelog ## [Unreleased](https://github.com/bids-standard/bids-specification/tree/HEAD) +- \[MISC] Introducing Stefan Appelhoff as the first Maintainer [#176](https://github.com/bids-standard/bids-specification/pull/176) ([chrisfilo](https://github.com/chrisfilo)) - \[FIX] Fixes spelling of continuous [#171](https://github.com/bids-standard/bids-specification/pull/171) ([emdupre](https://github.com/emdupre)) - \[FIX] changed reference of `dcm2nii` to `dcm2niix` [#166](https://github.com/bids-standard/bids-specification/pull/166) ([DimitriPapadopoulos](https://github.com/DimitriPapadopoulos)) - \[FIX] Removing a leftover file [#162](https://github.com/bids-standard/bids-specification/pull/162) ([chrisfilo](https://github.com/chrisfilo)) From b467a05f750691289f5d240a1b06e8f12d6831ce Mon Sep 17 00:00:00 2001 From: Dimitri Papadopoulos <3234522+DimitriPapadopoulos@users.noreply.github.com> Date: Fri, 15 Mar 2019 21:09:52 +0100 Subject: [PATCH 05/10] Spelling --- CODEOWNERS | 2 +- CONTRIBUTING.md | 4 ++-- DECISION-MAKING.md | 4 ++-- Release_Protocol.md | 2 +- src/01-introduction.md | 2 +- .../01-magnetic-resonance-imaging-data.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/CODEOWNERS b/CODEOWNERS index 0ef42927de..a2a1aa2467 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -5,7 +5,7 @@ # Request for Review) please add your GitHub username next to the file you want to # monitor below. -# Add your github name below to get notified about proposed releases +# Add your GitHub name below to get notified about proposed releases /src/CHANGES.md @chrisfilo @sappelhoff @CPernet # Individual sections diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b3ccb3db16..b1f67a1d85 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,7 +44,7 @@ The specification documents follow the [Markdown Style Guide](http://www.cirosan You can validate your changes against the guide using [remark](https://github.com/remarkjs/remark-lint) which works as a [standalone command line tool](https://github.com/remarkjs/remark/tree/master/packages/remark-cli) as well as [a plugin for various text editors](https://github.com/remarkjs/remark-lint#editor-integrations). Remark preserves consistent markdown styling across the contributions. Please ensure before submitting a contribution that you do not have any linter errors in your text editor. -You can also use [prettier](https://github.com/prettier/prettier) to automatically correct some of the style issuse that might be found in the proposed changes. +You can also use [prettier](https://github.com/prettier/prettier) to automatically correct some of the style issues that might be found in the proposed changes. We have deployed a continuous integrator ([circle CI](https://circleci.com/)) to further allow for integrating changes continuously. The CI is testing that the changes are inline with our standard styling. @@ -97,7 +97,7 @@ Try to keep the changes focused. If you submit a large amount of work in all in A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase. -A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your github notifications and be prepared to join in that conversation. +A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation. 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. diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index a83dc08e1d..32c9d064a7 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -91,9 +91,9 @@ when necessary. Current Maintainers: example it is perfectly fine for a PR to consist of content developed by a group of experts over an extended period of time via in person meetings and online collaborations using a Google Document. -1. To facilitate triaging of incoming PR you can subscribe to +1. To facilitate triage of incoming PR you can subscribe to notifications for new PRs proposing changes to specific files. To do this - add your Github name next to the file you want to subscribe to in the + add your GitHub name next to the file you want to subscribe to in the [CODEOWNERS](CODEOWNERS). This way you will be ask to review each relevant PR. Please mind that lack of your review will not prevent the PR from being merged so if you think the PR needs your attention, please review it diff --git a/Release_Protocol.md b/Release_Protocol.md index 519be65c63..3ff0608a0e 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -19,7 +19,7 @@ Important note: The pull request title **needs** to follow this protocol. REL: v ### This will open a period of discussion for 5 business days regarding if we are ready to release. This will also freeze all pull request merging. -If we determine we are ready to release, please have the PR submitter add an additional commit with the date in year-month-date format in parentheses after the version of the date of merging (not opening) (i.e. it should read v1.1.2 (2018-12-28)) and merge this PR. This will mark a new release. On the same day, please also do a github release. To do this please see below. +If we determine we are ready to release, please have the PR submitter add an additional commit with the date in year-month-date format in parentheses after the version of the date of merging (not opening) (i.e. it should read v1.1.2 (2018-12-28)) and merge this PR. This will mark a new release. On the same day, please also do a GitHub release. To do this please see below. ![GH-release-1](release_images/GH-release_1.png "GH-release-1") diff --git a/src/01-introduction.md b/src/01-introduction.md index e077e6cbb9..fe0f66b676 100644 --- a/src/01-introduction.md +++ b/src/01-introduction.md @@ -45,7 +45,7 @@ different backgrounds. ## Extensions The BIDS specification can be extended in a backwards compatible way and will -evolve over time. This is accomplished through community-driven BIDS Extention +evolve over time. This is accomplished through community-driven BIDS Extension Proposals (BEPs). For more information about the BEP process, and list of current BEP proposals, see [Extending the BIDS specification](06-extensions.md). diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index 905586e8b8..341602fd4b 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -20,7 +20,7 @@ by Ben Inglis: | HardcopyDeviceSoftwareVersion | (Deprecated) Manufacturer’s designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A `Hardcopy Device Software Version` | | MagneticFieldStrength | RECOMMENDED. Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 `Magnetic Field Strength` | | ReceiveCoilName | RECOMMENDED. Information describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field | -| ReceiveCoilActiveElements | RECOMMENDED. Information describing the active/selected elements of the receiver coil. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. As an example, for Siemens, coil channels are typically not activated/selected individually, but rather in pre-defined selectable "groups" of individual channels, and the list of the "groups" of elements that are active/selected in any given scan populates the `Coil String` entry in Siemen’s private DICOM fields (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the "active" coil elements. Since individual scans can sometimes not have the intended coil elements selected, it is preferable for this field to be populated directly from the DICOM for each individual scan, so that it can be used as a mechanism for checking that a given scan was collected with the intended coil elements selected | +| ReceiveCoilActiveElements | RECOMMENDED. Information describing the active/selected elements of the receiver coil. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. As an example, for Siemens, coil channels are typically not activated/selected individually, but rather in pre-defined selectable "groups" of individual channels, and the list of the "groups" of elements that are active/selected in any given scan populates the `Coil String` entry in Siemens’ private DICOM fields (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the "active" coil elements. Since individual scans can sometimes not have the intended coil elements selected, it is preferable for this field to be populated directly from the DICOM for each individual scan, so that it can be used as a mechanism for checking that a given scan was collected with the intended coil elements selected | | GradientSetType | RECOMMENDED. It should be possible to infer the gradient coil from the scanner model. If not, e.g. because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently | | MRTransmitCoilSequence | RECOMMENDED. This is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence` | | MatrixCoilMode | RECOMMENDED. (If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (e.g. GRAPPA, SENSE) imaging | From ebe69efd30a83f17970a3638fc23387d28402e5a Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Fri, 15 Mar 2019 12:16:13 -0700 Subject: [PATCH 06/10] [ENH] Alternative folder organization for raw, derived, and source data --- src/02-common-principles.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index ecaf302dc4..3dfc31a501 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -109,6 +109,29 @@ these data are to be included: 1. We RECOMMEND including the PDF print-out with the actual sequence parameters generated by the scanner in the `sourcedata` folder. +Alternatively one can organize their data in the following way + +```Text +my_dataset/ + sourcedata/ + ... + rawdata/ + dataset_description.json + participants.tsv + sub-01/ + sub-02/ + ... + derivatives/ + ... +``` + +In this example **only the `rawdata` subfolder needs to be BIDS compliant** +dataset. This specification does not prescribe anything about the contents of +`sourcedata` and `derivatives` folders in the above example - nor does it +prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. The above +example is just a convention that can be useful for organizing raw, source, and +derived data while maintaining BIDS compliancy of the raw data folder. + ## The Inheritance Principle Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any From b2c7706e845a167a6c07722cd16bef46aa13823f Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Fri, 15 Mar 2019 11:01:26 -0700 Subject: [PATCH 07/10] [INFRA] Adding instructions for naming PRs --- CONTRIBUTING.md | 16 ++++++++++++++++ pull_request_template.md | 17 +++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 pull_request_template.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b1f67a1d85..05fbc493d3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -95,6 +95,22 @@ Try to keep the changes focused. If you submit a large amount of work in all in #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) +Please keep the title of your pull request short but informative - it will +appear in the changelog. + +Use one of the following prefixes in the title of your pull request: + - `[ENH]` - enhancement of the specification that adds a new feature or + support for a new data type + - `[FIX]` - fix of a typo or language clarification + - `[INFRA]` - changes to the infrastructure automating the specification + release (for example building HTML docs etc.) + - `[MISC]` - everything else including changes to the file listing + contributors + +If you are opening a pull request to obtain early feedback, but the changes +are not ready to be merged (a.k.a. Work in Progress pull request) please +use [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 probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation. diff --git a/pull_request_template.md b/pull_request_template.md new file mode 100644 index 0000000000..82f0ea4863 --- /dev/null +++ b/pull_request_template.md @@ -0,0 +1,17 @@ +--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST --- + +- Please keep the title of your pull request short but informative - it will + appear in the changelog +- Use one of the following prefixes in the title of your pull request: + - `[ENH]` - enhancement of the specification that adds a new feature or + support for a new data type + - `[FIX]` - fix of a typo or language clarification + - `[INFRA]` - changes to the infrastructure automating the specification + release (for example building HTML docs etc.) + - `[MISC]` - everything else including changes to the file listing + contributors +- If you are opening a pull request to obtain early feedback, but the changes + are not ready to be merged (a.k.a. Work in Progress pull request) please + use [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) + +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- \ No newline at end of file From 63bcdbc0a259ecc400c753dac7d6285c806705d0 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Fri, 15 Mar 2019 11:22:51 -0700 Subject: [PATCH 08/10] Update CONTRIBUTING.md Co-Authored-By: chrisfilo --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05fbc493d3..3b115dac9b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -109,7 +109,7 @@ Use one of the following prefixes in the title of your pull request: If you are opening a pull request to obtain early feedback, but the changes are not ready to be merged (a.k.a. Work in Progress pull request) please -use [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/). +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. From 5186060c0a4271c92c974997b283fa72018c69de Mon Sep 17 00:00:00 2001 From: Chris Gorgolewski Date: Fri, 15 Mar 2019 11:30:36 -0700 Subject: [PATCH 09/10] add link to the changelog --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3b115dac9b..07ebbc74dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -96,7 +96,7 @@ Try to keep the changes focused. If you submit a large amount of work in all in #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) Please keep the title of your pull request short but informative - it will -appear in the changelog. +appear in the [changelog](src/CHANGES.md). Use one of the following prefixes in the title of your pull request: - `[ENH]` - enhancement of the specification that adds a new feature or From c0e95605a7d13bb7c248a0b2ee2ea335faf09755 Mon Sep 17 00:00:00 2001 From: Chris Markiewicz Date: Fri, 15 Mar 2019 12:25:26 -0700 Subject: [PATCH 10/10] Update pull_request_template.md Co-Authored-By: chrisfilo --- pull_request_template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pull_request_template.md b/pull_request_template.md index 82f0ea4863..7f01ddbc69 100644 --- a/pull_request_template.md +++ b/pull_request_template.md @@ -12,6 +12,6 @@ contributors - If you are opening a pull request to obtain early feedback, but the changes are not ready to be merged (a.k.a. Work in Progress pull request) please - use [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) + use a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) ---- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- \ No newline at end of file +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST ---