Skip to content

Latest commit

 

History

History
168 lines (134 loc) · 8.42 KB

CONTRIBUTING.md

File metadata and controls

168 lines (134 loc) · 8.42 KB
Raw

Contributing Guide

Welcome to the contributing guide!

This guide exists to help BIDS users to contribute to the BIDS validator with their own code. We cover:

  1. Knowledge that might be helpful to have (or acquire)
  2. How to set up your development environment for BIDS validator
  3. Ways to contribute code to BIDS validator (e.g., for a BIDS extension proposal)

If you find that something is unclear, please open an issue so that we can improve this guide.

Knowledge that will help you along the way

Git

We use git for source control. If you're not yet familiar with git, there are lots of great resources to help you get started! Some of our favorites include the git Handbook and the Software Carpentry introduction to git.

In particular, you will want to become conversant with the following operations:

You should also configure configure git for your user, so your commits are properly attributed.

GitHub

We use GitHub to manage contributions and have development discussions in the open. To participate, be sure you know how to

Coding knowledge

  • Familiarize yourself with the command line on your system (e.g., bash)
  • Basic knowledge about coding is helpful and familiarity with JavaScript is a big bonus, but you can contribute to the BIDS validator also without specific knowledge of JavaScript
  • Some knowledge about software testing (why we are doing it) would be nice

Using the development version of BIDS validator

  1. Make a GitHub account
  2. Install the required software:
    • git
    • NodeJS, including npm of version 7 or higher (check existing version with npm -v, to update an existing nodejs, we can suggest this guide.)
  3. In the GitHub interface, make a fork of https://github.com/bids-standard/bids-validator to your own user (called USER for the sake of the example)
  4. Open a command line and navigate to the location on your computer from where you want to develop BIDS validator and clone your fork of the repository
    • You will now have a new directory called bids-validator
    • navigate to that directory and run git status to verify that it's a git directory
    • run npm install to install the BIDS validator
  5. Upon inspection of the bids-validator repository we can find the "executable" BIDS validator, located in <...>/bids-validator/bin, where <...> is the path to your bids-validator repository
    • To make this executable available from the command line, we have to add it to the path. On Unix systems with bash as their default shell, this means editing the .bashrc file by adding the following line to the bottom of it: export PATH="$PATH:<...>/bids-validator/bin" ... Note that <...> again needs to be replaced by the path to your BIDS validator repository
    • Now whenever you open a new command line, we will have the bids-validator executable available. You can verify by opening a new command line and typing bids-validator --version, and it should print the version number

Now your development version of BIDS validator is set up and you can use it. Whenever you checkout a new branch in your git repository, the bids-validator executable is now pointing to that branch, and all changes in that branch will be reflected in the behavior of bids-validator.

Before you start making changes, there are some more important points to consider:

  1. We need to tell your git directory, that it has a remote counterpart (namely, the original BIDS validator). When that counterpart gets updated, you have to update your BIDS validator as well, to keep in sync.
    • run git remote add upstream https://github.com/bids-standard/bids-validator
    • then run git remote -v, and it should show four entries: two of type origin, and two of type upstream
    • origin refers to your fork of BIDS validator on GitHub, whereas upstream refers to the original BIDS validator repository on GitHub
    • you can use upstream to always stay up to date with changes that are being made on the original BIDS validator. For that, simply navigate to the master branch of your repository using git checkout master, and then run git pull upstream master
  2. When you get completely stuck with your repository and you just want to reset it to be an exact mirror of the original BIDS validator, you can run the following command (Note: this will discard all current changes):
    • first checkout your master: git checkout master
    • then run: git reset --hard upstream/master

Extending the BIDS validator for a BIDS Extension Proposal (BEP)

Regular expressions

A lot of validation of BIDS files and directories is happening through regular expressions. You can see the regular expressions here.

Changing the regular expressions can be a delicate thing, so we recommend testing your regular expressions exhaustively. A helpful website for that can be https://regex101.com/, where you can test regular expressions in your browser, and even save and share them.

JSON schemas

Another big chunk of BIDS validation is happening through JSON schemas. In BIDS, a lot of metadata is saved in JSON files, which are very well defined and readable by a computer. With these properties, we can make requirements of how a JSON ought to look like. You can find our JSON schemas here.

As with regular expressions, we recommend lots of testing on the JSON schemas. You can easily have a first try of that using a website like https://www.jsonschemavalidator.net/. Simply copy over a schema from BIDS validator to the left field, and try to comply to the schema, or trigger an error by typing in a JSON to the right field.

Writing tests

For every change you make it is important to include a test. That way, we can make sure that the behavior of BIDS validator is as expected, and furthermore we will be notified whenever a contributor makes a change in the code that breaks the expected behavior of the BIDS validator.

A test usually provides some known data, and let's the software run over it ... just to check whether the output is as we know it should be (because we know the data, after all).

You can get a good impression using the following links:

For more information on how to run the tests check the testing section of the README.