diff --git a/.circleci/config.yml b/.circleci/config.yml index 333308bf2f..483269e7ce 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -37,11 +37,20 @@ jobs: at: ~/build - run: command: | + if (! git log -1 --pretty=%b | grep REL:) ; then chmod a+rX -R ~ linkchecker -t 1 ~/build/site/ # check external separately by pointing to all *html so no # failures for local file:/// -- yoh found no better way, - linkchecker -t 1 --check-extern --ignore-url 'file:///.*' --ignore-url https://fonts.gstatic.com ~/build/site/*html ~/build/site/*/*.html + linkchecker -t 1 --check-extern \ + --ignore-url 'file:///.*' \ + --ignore-url https://fonts.gstatic.com \ + --ignore-url "https://github.com/bids-standard/bids-specification/(pull|tree)/.*" \ + --ignore-url "https://github.com/[^/]*" \ + ~/build/site/*html ~/build/site/*/*.html + else + echo "Release PR - do nothing" + fi build_docs_pdf: working_directory: ~/bids-specification/pdf_build_src diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 4fb314900d..90012a90ab 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -2,8 +2,68 @@ ## Introduction -The Brain Imaging Data Structure (BIDS) community set out the following -decision-making rules with the intention to: +In October 2019, the BIDS community [voted](https://github.com/bids-standard/bids-specification/issues/355) +to ratify a governance structure and to elect five members as a *Steering Group* +to oversee the development and adoption of the standard. + +The document outlining our governance structure is hosted on the BIDS website: +[https://bids.neuroimaging.io/governance.html](https://bids.neuroimaging.io/governance.html) + +In the following, we list the current members of subgroups detailed in the +BIDS governance. + +**Steering Group** + +| Name +|------------------------------------------------------------------------------| +| Guiomar Niso ([@guiomar](https://github.com/guiomar)) | +| Melanie Ganz ([@melanieganz](https://github.com/melanieganz)) | +| Robert Oostenveld ([@robertoostenveld](https://github.com/robertoostenveld)) | +| Russel Poldrack ([@poldrack](https://github.com/poldrack)) | +| Kristie Whitaker ([@KristieJane](https://github.com/KristieJane)) | + +**Maintainers Group** + +| Name | Time commitment | Scope | +|--------------------------------------------------------------------------------|-----------------|-----------------------| +| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | | +| Chris Markiewicz ([@effigies](https://github.com/effigies)) | 5h/week | | +| Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) | 5h/week | Community development | + +In addition to the [BIDS Governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group) +classification of a maintainer, maintainers may declare a limited scope of responsibility. +Such a scope can range from maintaining a modality supported in the specification to nurturing a +welcoming BIDS community. +One or more scopes can be chosen by the maintainer and agreed upon by the Maintainers Group. +A maintainer is primarily responsible for issues within their chosen scope(s), although +contributions elsewhere are welcome, as well. + +**BEP Leads Group** + +Leaders of BIDS Extension Proposals are listed in the +[table of BEPs](https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification). + +**Contributors Group** + +Contributors are listed in [Appendix I](https://bids-specification.readthedocs.io/en/stable/99-appendices/01-contributors.html) +of the BIDS specification. Contributors who have not yet entered their name +into this list are encouraged to edit the [Contributors WIKI page](https://github.com/bids-standard/bids-specification/wiki/Contributors) +with their name, using the emojis listed in the WIKI to indicate their +contributions. + +**Other groups** + +The following groups not listed in detail. Please learn more about these groups +from the [governance document](https://bids.neuroimaging.io/governance.html). + +- BEP working groups +- Advisory Group +- BIDS Community + +## GitHub Workflow + +For the day-to-day work on the BIDS specification, we currently abide by the +following rules with the intention to: - Strive for consensus. - Promote open discussions. @@ -16,24 +76,6 @@ decision-making rules with the intention to: The rules outlined below are inspired by the [lazy consensus system used in the Apache Foundation](https://www.apache.org/foundation/voting.html) and heavily depends on [GitHub Pull Request Review system](https://help.github.com/articles/about-pull-requests/). -## Definitions - -**Repository** - [https://github.com/bids-standard/bids-specification](https://github.com/bids-standard/bids-specification) - -**Contributor** - a person listed in the Appendix I: Contributors. The -community decides on the content of this file using the same process as any -other change to the Repository (see below) allowing the meaning of "Contributor" -to evolve independently of the Decision-making rules. - -**Maintainer** - a Contributor responsible for the long term health of the -project and the community. Maintainers have additional rights (see Rules) -helping them to resolve conflicts and increase the pace of the development -when necessary. Current Maintainers: - -| Name | Time commitment | -|-----------------------------------------------------------------|-----------------| -| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | - ## Rules 1. Every modification of the specification (including a correction of a typo, diff --git a/README.md b/README.md index e01c6f2c66..b681418fc3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ [![Build Status](https://travis-ci.com/bids-standard/bids-specification.svg?branch=master)](https://travis-ci.com/bids-standard/bids-specification) [![CircleCI](https://circleci.com/gh/bids-standard/bids-specification.svg?style=svg)](https://circleci.com/gh/bids-standard/bids-specification) [![@BIDSstandard](http://img.shields.io/twitter/follow/bidsstandard.svg?style=social)](https://twitter.com/BIDSstandard) - +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3686061.svg)](https://doi.org/10.5281/zenodo.3686061) bids-logo diff --git a/Release_Protocol.md b/Release_Protocol.md index c2dedcd475..580ea5574c 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -57,14 +57,14 @@ If the version preceding the `-dev` is not the target version, update the versio In the figure below, we update `v1.2.0-dev` to `v1.2.0`. ![dev-to-stable](release_images/site_name_release_1.2dev-1.2.png "dev-to-stable") -Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed. +Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed. Synchronize the [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md) with the [Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Contributors) to ensure all contributors are duly credited. Be sure not to remove credits if both have been edited. -Please change the previous version links from GitHub to ReadTheDocs. +Please change the previous version links from GitHub to ReadTheDocs. In the figure below, we update v1.2.2. ![github-to-rtd](release_images/GitHub_to_RTD_spec_rendering.png "github-to-rtd") @@ -118,7 +118,7 @@ $ git push rel/1.2.0 ### 5. Set release date and merge -On the day of release, please ensure the release branch aligns with the master branch. +On the day of release, please ensure the release branch aligns with the master branch. The current date should be added to/updated in the changelog in the form YYYY-MM-DD. The date should be placed after the link to the versioned URL. @@ -131,7 +131,20 @@ For example: Verify that the pull request title matches "REL: vX.Y.Z" and merge the pull request. -### 6. Tag the release +### 6. Get the built PDF + +Upon each commit to the `master` branch, CircleCI builds a PDF version of the +specification (see `.circleci/config.yml` and the `pdf_build_src` directory). + +So after merging the new "stable" version into `master`, wait for the CircleCI +jobs to finish and then check the built PDF using this link: + +`https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master` + +Download the PDF and hold it ready for upload to our Zenodo archive. See the +*Uploading the stable PDF to Zenodo* step below. + +### 7. Tag the release GitHub's release mechanism does not have all of the features we need, so manually tag the release in your local repository. @@ -155,7 +168,7 @@ There are four components to the tag command: 4. `upstream/master` instructs `git` to tag the most recent commit on the `master` branch of the `upstream` remote. -### 7. Create a GitHub release +### 8. Create a GitHub release Some GitHub processes may only trigger on a GitHub release, rather than a tag push. To make a GitHub release, go to the [Releases @@ -177,10 +190,10 @@ Verify ReadTheDocs builds complete and publish. If needed, manually trigger [builds](https://readthedocs.org/projects/bids-specification/builds/) for `stable` and the most recent tag. -### 8. Edit the mkdocs.yml file site_name to set a new development version +### 9. Edit the mkdocs.yml file site_name to set a new development version -Please submit a PR with the title `REL: -dev`. -This should be the first merged PR in the new version. +Please commit to `master` with the title `REL: -dev`. +This should be the first commit in the new version. This process is illustrated below. ![stable-to-dev](release_images/site_name_release_1.2-1.3dev.png "stable-to-dev") @@ -190,10 +203,24 @@ version of the next *intended* release, followed by `-dev`. For example, after the 1.3.0 release, either `1.3.1-dev` or `1.4.0-dev` would be reasonable, based on the expected next version. -### 9. Sharing news of the release +### 10. Uploading the stable PDF to Zenodo + +1. Open a private browser window +1. Log into https://github.com with the `bids-maintenance` user (credentials + are available from the BIDS maintainer group) +1. Open a new tab at https://zenodo.org and "log in via GitHub", you'll then + be on the `bids-maintenance` Zenodo account +1. Navigate to the [archive of our BIDS specification PDFs](https://doi.org/10.5281/zenodo.3686061) +1. Click on "add new version" +1. For a new version, upload the new PDF, naming it consistently with the other + PDFs: `BIDS-Specification-vX.X.X.pdf` (replace `X.X.X` with the new version) +1. Remove all other files from the upload +1. Edit the following fields: + 1. publication date + 1. version +1. Double check that everything is in order, then save and publish + +### 11. Sharing news of the release Please share news of the release on the [identified platforms](https://docs.google.com/spreadsheets/d/16SAGK3zG93WM2EWuoZDcRIC7ygPc5b7PDNGpFyC3obA/edit#gid=0). Please use our previous release posts as a guide. - - - diff --git a/mkdocs.yml b/mkdocs.yml index 24acea42cf..5a2650f1ee 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,4 @@ -site_name: Brain Imaging Data Structure v1.3.0-dev +site_name: Brain Imaging Data Structure v1.3.1-dev theme: name: material custom_dir: theme_customizations/ @@ -31,6 +31,7 @@ nav: - Task events: 04-modality-specific-files/05-task-events.md - Physiological and other continuous recordings: 04-modality-specific-files/06-physiological-and-other-continuous-recordings.md - Behavioral experiments (with no MRI): 04-modality-specific-files/07-behavioral-experiments.md + - Genetic Descriptor: 04-modality-specific-files/08-genetic-descriptor.md - Longitudinal and multi-site studies: 05-longitudinal-and-multi-site-studies.md - BIDS Extension Proposals: 06-extensions.md - Appendix: diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 0e66a45f93..a00d1e597c 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -6,21 +6,22 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)]. -Throughout this specification we use a list of terms. To avoid +Throughout this specification we use a list of terms and abbreviations. To avoid misunderstanding we clarify them here. -1. Dataset - a set of neuroimaging and behavioral data acquired for a purpose - of a particular study. A dataset consists of data acquired from one or more - subjects, possibly from multiple sessions. +1. **Dataset** - a set of neuroimaging and behavioral data acquired for a + purpose of a particular study. A dataset consists of data acquired from one + or more subjects, possibly from multiple sessions. -1. Subject - a person or animal participating in the study. +1. **Subject** - a person or animal participating in the study. Used + interchangeably with term **Participant**. -1. Session - a logical grouping of neuroimaging and behavioral data consistent - across subjects. Session can (but doesn't have to) be synonymous to a visit - in a longitudinal study. In general, subjects will stay in the scanner - during one session. However, for example, if a subject has to leave the - scanner room and then be re-positioned on the scanner bed, the set of MRI - acquisitions will still be considered as a session and match sessions +1. **Session** - a logical grouping of neuroimaging and behavioral data + consistent across subjects. Session can (but doesn't have to) be synonymous + to a visit in a longitudinal study. In general, subjects will stay in the + scanner during one session. However, for example, if a subject has to leave + the scanner room and then be re-positioned on the scanner bed, the set of + MRI acquisitions will still be considered as a session and match sessions acquired in other subjects. Similarly, in situations where different data types are obtained over several visits (for example fMRI on one day followed by DWI the day after) those can be grouped in one session. Defining multiple @@ -28,34 +29,51 @@ misunderstanding we clarify them here. are planned and performed on all -or most- subjects, often in the case of some intervention between sessions (e.g., training). -1. Data acquisition - a continuous uninterrupted block of time during which a - brain scanning instrument was acquiring data according to particular +1. **Data acquisition** - a continuous uninterrupted block of time during which + a brain scanning instrument was acquiring data according to particular scanning sequence/protocol. -1. Data type - a functional group of different types of data. In BIDS we define - eight data types: func (task based and resting state functional MRI), dwi - (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as - field maps), anat (structural imaging such as T1, T2, etc.), meg - (magnetoencephalography), eeg (electroencephalography), ieeg (intracranial - electroencephalography), beh (behavioral). +1. **Data type** - a functional group of different types of data. In BIDS we + define eight data types: `func` (task based and resting state functional MRI), + `dwi` (diffusion weighted imaging), `fmap` (field inhomogeneity mapping data + such as field maps), `anat` (structural imaging such as T1, T2, etc.), `meg` + (magnetoencephalography), `eeg` (electroencephalography), `ieeg` (intracranial + electroencephalography), `beh` (behavioral). -1. Task - a set of structured activities performed by the participant. Tasks - are usually accompanied by stimuli and responses, and can greatly vary in - complexity. For the purpose of this specification we consider the so-called +1. **Task** - a set of structured activities performed by the participant. + Tasks are usually accompanied by stimuli and responses, and can greatly vary + in complexity. For the purpose of this specification we consider the so-called "resting state" a task. In the context of brain scanning, a task is always tied to one data acquisition. Therefore, even if during one acquisition the subject performed multiple conceptually different behaviors (with different sets of instructions) they will be considered one (combined) task. -1. Event - a stimulus or subject response recorded during a task. Each event - has an onset time and duration. Note that not all tasks will have recorded - events (e.g., resting state). +1. **Event** - a stimulus or subject response recorded during a task. Each + event has an onset time and duration. Note that not all tasks will have + recorded events (e.g., “resting state”). -1. Run - an uninterrupted repetition of data acquisition that has the same +1. **Run** - an uninterrupted repetition of data acquisition that has the same acquisition parameters and task (however events can change from run to run due to different subject response or randomized nature of the stimuli). Run is a synonym of a data acquisition. +1. **``** - a numeric value, possibly prefixed with arbitrary number of + 0s for consistent indentation, e.g., it is `01` in `run-01` following + `run-` specification. + +1. **`