Merge remote-tracking branch 'upstream/common-derivatives' into enh/r…

…esolution-density
bids-standard · May 21, 2020 · bb94c0b · bb94c0b
2 parents 0b99b7c + 1fe71b8
commit bb94c0b
Show file tree

Hide file tree

Showing 45 changed files with 1,186 additions and 424 deletions.
diff --git a/.circleci/artifact_path b/.circleci/artifact_path
@@ -1 +1 @@
-0/home/circleci/project/site/01-introduction.html
+0/site/01-introduction.html
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -37,11 +37,36 @@ 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
+    docker:
+      - image: danteev/texlive:TL2017
+    steps:
+      - checkout:
+          path: ~/bids-specification
+      - run:
+          name: generate pdf version docs
+          command: sh build_pdf.sh
+      - store_artifacts:
+          path: bids-spec.pdf
+      - run:
+          name: remove pdf version from repo
+          command: rm bids-spec.pdf
 
 # Auto changelog collector
   github-changelog-generator:
@@ -57,7 +82,7 @@ jobs:
            working_directory: ~/build
            command: |
              if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then
-             github_changelog_generator --user bids-standard --project bids-specification --token ${CHANGE_TOKEN} --output ~/build/CHANGES.md --base ~/build/src/pregh-changes.md --header-label Changelog --no-issues --no-issues-wo-labels --no-filter-by-milestone --no-compare-link --pr-label ""
+             github_changelog_generator --user bids-standard --project bids-specification --token ${CHANGE_TOKEN} --output ~/build/CHANGES.md --base ~/build/src/pregh-changes.md --header-label "# Changelog" --no-issues --no-issues-wo-labels --no-filter-by-milestone --no-compare-link --pr-label ""
              cat ~/build/CHANGES.md
              mv ~/build/CHANGES.md ~/build/src/CHANGES.md
              else
@@ -130,8 +155,8 @@ jobs:
              merge_messsge=$(git log -1 | grep Merge | grep "pull")
              PR_number=$(echo $merge_messsge | cut -d ' ' -f 4)
              git config credential.helper 'cache --timeout=120'
-             git config user.email "franklin.feingold@gmail.com"
-             git config user.name "Changelog-bot"
+             git config user.email "bids.maintenance@gmail.com"
+             git config user.name "bids-maintenance"
              git add ~/build/src/CHANGES.md
              git commit -m "[DOC] Auto-generate changelog entry for PR ${PR_number}"
              git push https://${CHANGE_TOKEN}@github.com/bids-standard/bids-specification.git master
@@ -163,3 +188,12 @@ workflows:
           filters:
                branches:
                    only: master
+      # Ensure that build_docs_pdf always runs last, so that we can use the CircleCI API link for the "latest" artifact
+      # https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master
+      - build_docs_pdf:
+          requires:
+               - build_docs
+               - linkchecker
+               - github-changelog-generator
+               - remark
+               - Changelog-bot
diff --git a/.github/ISSUE_TEMPLATE/blank.md b/.github/ISSUE_TEMPLATE/blank.md
@@ -0,0 +1,7 @@
+---
+name: Blank issue
+about: Create an issue without a template.
+title: ''
+labels: ''
+assignees: ''
+---
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+---
+
+--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE ISSUE ---
+
+Please ...
+
+- ... describe your problem in detail.
+- ... describe what you expected instead of your problem.
+- ... provide a link to the part of the BIDS specification that is relevant.
+
+--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE ISSUE ---
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: BIDS NeuroStars forum
+    url: https://neurostars.org/
+    about: Ask (and answer) concrete technical questions or about implementation details around BIDS.
+  - name: BIDS mailing list
+    url: https://groups.google.com/forum/#!forum/bids-discussion
+    about: Use the BIDS mailing list for announcements, and to draw attention to any item related to BIDS
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+---
+
+--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE ISSUE ---
+
+- Have you checked our contributing guide? It's a helpful resource: https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md
+
+- Is your idea backwards compatible? If not, please add it to the BIDS 2.0 Google Doc instead of opening an issue: https://docs.google.com/document/d/1LEgsMiisGDe1Gv-hBp1EcLmoz7AlKj6VYULUgDD3Zdw/
+
+- Is there already a group working on your idea? Check the BIDS extension proposals: https://bids.neuroimaging.io/get_involved.html#extending-the-bids-specification
+
+- Will your idea potentially require a large effort? Read BEP lead guidelines: https://docs.google.com/document/d/1pWmEEY-1-WuwBPNy5tDAxVJYQ9Een4hZJM06tQZg8X4/
+
+- When you suggest your idea, please try to supply (mock) examples!
+
+--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE ISSUE ---
diff --git a/.gitignore b/.gitignore
@@ -1 +1,4 @@
-site/
+site/
+.DS_Store
+src/.DS_Store
+src/04-modality-specific-files/.DS_Store
diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md
@@ -2,8 +2,60 @@
 
 ## 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 |
+|--------------------------------------------------------------------------------|-----------------|
+| 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         |
+
+**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 +68,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
@@ -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)
 
 <img src="./BIDS_logo/BIDS_logo_black_transparent_background_crop.png" alt="bids-logo" width="600"/>
 
@@ -11,8 +11,29 @@ organisation of neuroimaging data.
 In this repository, we develop the
 [BIDS specification](https://bids-specification.readthedocs.io/en/latest/).
 
-**Want to learn more about working with BIDS? Have a question, comment, or suggestion?**
-Open or comment on one of our [NeuroStars issues](https://neurostars.org/tags/bids) or check out the [BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit)!
+# When to use BIDS
+
+To organize your data in BIDS, all you need is neuro data, a computer, and the
+[BIDS specification](https://bids-specification.readthedocs.io/en/stable/).
+
+BIDS currently supports MRI, MEG, EEG, iEEG, behavioral, and physiological data
+and more modalities will be added.
+
+# Formatting your data with BIDS
+
+As a dataset curator, the GitHub repository and all files therein can be safely ignored.
+Users should focus on [the rendered content](https://bids-specification.readthedocs.io/en/stable/).
+The specification is provided in the form of a webpage, built using
+[MkDocs](https://www.mkdocs.org/) and [Read the Docs](https://readthedocs.org/).
+
+*Want to learn more about working with BIDS? Have a question, comment, or suggestion?*
+
+1. Read some introductory material, most likely the very basic problems have already been addressed!
+  - [BIDS Starter Kit](https://github.com/bids-standard/bids-starter-kit) for tutorials, wikis, templates, ...
+2. Post your question in one of several channels where BIDS members are active
+  - the [NeuroStars](https://neurostars.org/tags/bids) discourse forum
+  - the [Google group](https://groups.google.com/forum/#!forum/bids-discussion), for broader discussions surrounding BIDS
+  - the [specification repository issue page](https://github.com/bids-standard/bids-specification/issues), if you found inconsistencies, typos, or other issues with the BIDS specification itself
 
 # Contributing to BIDS
 

diff --git a/Release_Protocol.md b/Release_Protocol.md
@@ -35,7 +35,7 @@ $ git fetch upstream
 $ git checkout -b rel/1.2.0 upstream/master
 ```
 
-### 2. Update the version and the contributors list
+### 2. Update the version, contributors list, previous version URLs, and the Changelog
 
 Change the "Unreleased" heading in
 [src/CHANGES.md](https://github.com/bids-standard/bids-specification/blob/master/src/CHANGES.md)
@@ -57,13 +57,28 @@ If the version preceding the `-dev` is not the target version, update the versio
 In the figure below, we update `v1.2.0-dev` to `v1.2.0`.
 ![dev-to-stable](release_images/site_name_release_1.2dev-1.2.png "dev-to-stable")
 
-Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed. 
+Note: this will make our continuous integration ([CircleCI](https://circleci.com/)) fail. This fails because the URL of the new ReadTheDocs rendering has not been generated at this time. It will be generated once the GitHub release has been completed.
 
 Synchronize the [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md)
 with the [Contributors wiki page](https://github.com/bids-standard/bids-specification/wiki/Contributors)
 to ensure all contributors are duly credited.
 Be sure not to remove credits if both have been edited.
 
+Please change the previous version links from GitHub to ReadTheDocs.
+In the figure below, we update v1.2.2.
+![github-to-rtd](release_images/GitHub_to_RTD_spec_rendering.png "github-to-rtd")
+
+Remove `REL:` entries in [src/CHANGES.md](https://github.com/bids-standard/bids-specification/blob/master/src/CHANGES.md).
+
+```Diff
+- REL: v1.2.2 #405 (franklin-feingold)
+```
+
+Review `src/CHANGES.md` to ensure that the document produces a changelog that is useful to a
+reader of the specification.
+For example, several small PRs fixing typos might be merged into a single line-item, or less
+important changes might be moved down the list to ensure that large changes are more prominent.
+
 ### 3. Commit changes and push to upstream
 
 By pushing `rel/` branches to the main repository, the chances of continuous integration
@@ -84,7 +99,7 @@ Minor revisions may be made using GitHub's [suggestion
 feature](https://help.github.com/en/articles/incorporating-feedback-in-your-pull-request).
 For larger changes, pull requests should be made against `master`.
 
-**Merging other pull requests during this period requires agreement in this discussion.**
+**Merging other pull requests during this period requires agreement among BIDS Maintainers.**
 
 There are no hard-and-fast rules for what other pull requests might be merged, but the focus
 should generally be on achieving a self-consistent, backwards-compatible document.
@@ -95,22 +110,16 @@ probably wait.
 If `master` is updated, it should be merged into the `rel/<verison>` branch:
 
 ```Shell
-$ get fetch upstream
+$ git fetch upstream
 $ git checkout rel/1.2.0
 $ git merge upstream/master
 $ git push rel/1.2.0
 ```
 
-### 5. Clean the changelog
+### 5. Set release date and merge
 
-Review `src/CHANGES.md` to ensure that the document produces a changelog that is useful to a
-reader of the specification.
-For example, several small PRs fixing typos might be merged into a single line-item, or less
-important changes might be moved down the list to ensure that large changes are more prominent.
-
-### 6. Set release date and merge
-
-On the day of release, the current date should be added to/updated in the changelog in the form
+On the day of release, please ensure the release branch aligns with the master branch.
+The current date should be added to/updated in the changelog in the form
 YYYY-MM-DD.
 The date should be placed after the link to the versioned URL.
 For example:
@@ -122,6 +131,19 @@ For example:
 
 Verify that the pull request title matches "REL: vX.Y.Z" and merge the pull request.
 
+### 6. Get the built PDF
+
+Upon each commit to the `master` branch, CircleCI builds a PDF version of the
+specification (see `.circleci/config.yml` and the `pdf_build_src` directory).
+
+So after merging the new "stable" version into `master`, wait for the CircleCI
+jobs to finish and then check the built PDF using this link:
+
+`https://circleci.com/api/v1.1/project/github/bids-standard/bids-specification/latest/artifacts/0/bids-spec.pdf?branch=master`
+
+Download the PDF and hold it ready for upload to our Zenodo archive. See the
+*Uploading the stable PDF to Zenodo* step below.
+
 ### 7. Tag the release
 
 GitHub's release mechanism does not have all of the features we need, so manually tag the release
@@ -170,8 +192,8 @@ for `stable` and the most recent tag.
 
 ### 9. Edit the mkdocs.yml file site_name to set a new development version
 
-Please submit a PR with the title `REL: <version>-dev`.
-This should be the first merged PR in the new version.
+Please commit to `master` with the title `REL: <version>-dev`.
+This should be the first commit in the new version.
 This process is illustrated below.
 
 ![stable-to-dev](release_images/site_name_release_1.2-1.3dev.png "stable-to-dev")
@@ -180,3 +202,25 @@ Note that the development version number should be larger than the last release,
 version of the next *intended* release, followed by `-dev`.
 For example, after the 1.3.0 release, either `1.3.1-dev` or `1.4.0-dev` would be reasonable, based
 on the expected next version.
+
+### 10. Uploading the stable PDF to Zenodo
+
+1. Open a private browser window
+1. Log into https://github.com with the `bids-maintenance` user (credentials
+   are available from the BIDS maintainer group)
+1. Open a new tab at https://zenodo.org and "log in via GitHub", you'll then
+   be on the `bids-maintenance` Zenodo account
+1. Navigate to the [archive of our BIDS specification PDFs](https://doi.org/10.5281/zenodo.3686061)
+1. Click on "add new version"
+1. For a new version, upload the new PDF, naming it consistently with the other
+   PDFs: `BIDS-Specification-vX.X.X.pdf` (replace `X.X.X` with the new version)
+1. Remove all other files from the upload
+1. Edit the following fields:
+    1. publication date
+    1. version
+1. Double check that everything is in order, then save and publish
+
+### 11. Sharing news of the release
+
+Please share news of the release on the [identified platforms](https://docs.google.com/spreadsheets/d/16SAGK3zG93WM2EWuoZDcRIC7ygPc5b7PDNGpFyC3obA/edit#gid=0).
+Please use our previous release posts as a guide.