State of the BEP (Do not merge)

.circleci/config.yml

@@ -2,142 +2,180 @@ version: 2
 jobs:
   build_docs:
     docker:
-      - image: circleci/python:3.6.6
+      - image: circleci/python:3.8
     steps:
+      # checkout code to default ~/project
       - checkout
-      - run: sudo chown -R circleci:circleci /usr/local/bin
-      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages
-      - restore_cache:  # ensure this step occurs *before* installing dependencies
-          key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
       - run:
+          name: install dependencies
           command: |
-            sudo pip install pip==18.0
-            sudo pip install pipenv==2018.7.1
-            pipenv install
-      - save_cache:
-          key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
-          paths:
-            - ".venv"
-            - "/usr/local/bin"
-            - "/usr/local/lib/python3.6/site-packages"
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt
       - run:
           name: generate docs
-          command: pipenv run mkdocs build --clean --strict --verbose
-      - store_artifacts:
-          path: site
+          command: mkdocs build --clean --strict --verbose
       - persist_to_workspace:
-          root: .
+          # the mkdocs build outputs are in ~/project/site
+          root: ~/project
           paths: site
 
   linkchecker:
     docker:
       - image: yarikoptic/linkchecker:9.4.0.anchorfix1-1
     steps:
+      # checkout code to default ~/project
+      - checkout
       - attach_workspace:
-          at: ~/build
+          # mkdocs build outputs will be in ~/project/site
+          at: ~/project
+      - run:
+          name: install git
+          command: |
+            apt update -y
+            apt install git-all -y
+      - run:
+          name: check links
+          command: |
+            git status
+            if (! git log -1 --pretty=oneline | grep REL:) ; then
+              chmod a+rX -R ~
+              linkchecker -t 1 ~/project/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 \
+                --ignore-url "https://github.com/bids-standard/bids-specification/(pull|tree)/.*" \
+                --ignore-url "https://github.com/[^/]*" \
+                ~/project/site/*html ~/project/site/*/*.html
+            else
+              echo "Release PR - do nothing"
+            fi
+
+  build_docs_pdf:
+    docker:
+      - image: danteev/texlive:latest
+    steps:
+      # checkout code to default ~/project
+      - checkout
+      - run:
+          name: install dependencies
+          command: |
+            apt-get update && apt install -y python3-pip
+            python3 -m pip install --upgrade pip
+            python3 -m pip install -r  ~/project/requirements.txt
+      - run:
+          name: install font that works with unicode emojis
+          command: apt-get update && apt-get install -y fonts-symbola
       - run:
+          name: generate pdf version docs
           command: |
-            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
+            cd ~/project/pdf_build_src
+            bash build_pdf.sh
+            mv ~/project/pdf_build_src/bids-spec.pdf ~/project/bids-spec.pdf
+      - store_artifacts:
+          path: bids-spec.pdf
 
-# Auto changelog collector
+  # Auto changelog collector
   github-changelog-generator:
-    working_directory: ~/build
     docker:
       - image: ferrarimarco/github-changelog-generator:1.14.3
     steps:
       - setup_remote_docker:
-           version: 17.11.0-ce
+          version: 18.06.0-ce
+      # checkout code to default ~/project
       - checkout
       - run:
-           name: Build changelog
-           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 ""
-             cat ~/build/CHANGES.md
-             mv ~/build/CHANGES.md ~/build/src/CHANGES.md
-             else
-             echo "Commit or Release, do nothing"
-             fi
+          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 \
+                --user bids-standard \
+                --project bids-specification \
+                --token ${CHANGE_TOKEN} \
+                --output ~/changelog_build/CHANGES.md \
+                --base ~/project/src/pregh-changes.md \
+                --header-label "# Changelog" \
+                --no-issues \
+                --no-issues-wo-labels \
+                --no-filter-by-milestone \
+                --no-compare-link \
+                --pr-label "" \
+                --release-branch master
+              cat ~/changelog_build/CHANGES.md
+            else
+              echo "Commit or Release, do nothing"
+            fi
       - persist_to_workspace:
-             root: .
-             paths: src
+          # raw generated changelog in ~/changelog_build/CHANGES.md
+          root: ~/.
+          paths: changelog_build
 
-# Clear remark test
+  # Run remark on the auto generated changes.md file
   remark:
-    working_directory: ~
     docker:
       - image: node:latest
     steps:
+      # checkout code to default ~/project
       - checkout
       - attach_workspace:
-          at: ~/build
+          # the freshly built CHANGES.md will be in ~/changelog_build/CHANGES.md
+          at: ~/.
       - run:
-          name: update-npm
-          command: |
-           cd ~
-           npm install npm@latest
+          name: install remark and extensions
+          command: npm install `cat npm-requirements.txt`
       - run:
-          name: get remark
-          command: |
-           cd ~
-           npm install remark remark-cli
-      - run:
-          name: get remark styles
-          command: |
-           cd ~
-           npm install remark-cli@5.0.0 remark-lint@6.0.2 remark-preset-lint-recommended@3.0.2 remark-preset-lint-markdown-style-guide@2.1.2
-      - run: # remark the auto generated changes.md
           name: remark on autogenerated CHANGES.md
+          # format changelog, then use sed to change * to -, then lint changelog
           command: |
-             cd ~/project
-             if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then
-             mkdir ~/project/src/tmp
-             cat ~/build/src/CHANGES.md
-             cp ~/build/src/CHANGES.md ~/project/src/CHANGES.md
-             ~/node_modules/.bin/remark ~/project/src/CHANGES.md -o ~/project/src/tmp/CHANGES.md
-             ~/node_modules/.bin/remark ~/project/src/tmp/CHANGES.md --frail
-             else
-             echo "Commit or Release, do nothing"
-             mkdir ~/project/src/tmp
-             touch ~/project/src/tmp/empty.txt
-             fi
+            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:
-             root: ~/project/src
-             paths: tmp
+          # fixed+linted changelog in ~/changelog_build/CHANGES.md
+          root: ~/.
+          paths: changelog_build
 
-# Push built changelog to repo
+  # Push built changelog to repo
   Changelog-bot:
-    working_directory: ~/build
     docker:
       - image: circleci/openjdk:8-jdk
     steps:
       - setup_remote_docker:
-           version: 17.11.0-ce
+          version: 17.11.0-ce
+      # checkout code to default ~/project
       - checkout
       - attach_workspace:
-            at: ~/build
+          # fixed+linted changelog in ~/changelog_build/CHANGES.md
+          at: ~/.
       - deploy:
-           name: Changelog deployment
-           working_directory: ~/build
-           command: |
-             if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then
-             mv ~/build/tmp/CHANGES.md ~/build/src/CHANGES.md
-             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 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
-             else
-             echo "Commit or Release, do nothing"
-             fi
+          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:
   version: 2
@@ -149,17 +187,26 @@ workflows:
             - build_docs
       - github-changelog-generator:
           filters:
-               branches:
-                   only: master
+            branches:
+              only: master
       - remark:
           requires:
-               - github-changelog-generator
+            - github-changelog-generator
           filters:
-               branches:
-                   only: master
+            branches:
+              only: master
       - Changelog-bot:
           requires:
-               - remark
+            - remark
           filters:
-               branches:
-                   only: master
+            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

.github/ISSUE_TEMPLATE/blank.md

@@ -0,0 +1,7 @@
+---
+name: Blank issue
+about: Create an issue without a template.
+title: ''
+labels: ''
+assignees: ''
+---

.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 ---

.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

.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 open an issue in the bids-2-devel repository instead of here: https://github.com/bids-standard/bids-2-devel
+
+- 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 ---

.github/pull_request_template.md

@@ -0,0 +1,25 @@
+--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST ---
+
+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 ensure your name is credited on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-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 contact @franklin-feingold or @sappelhoff.
+- 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
+  - `[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 PR to obtain early feedback, but the changes
+  are not ready to be merged (a.k.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.
+
+--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST ---