Contributing guide

Project organization

  • +qb/ - The main namespace with the core packages and functions:

    • +MP2RAGE/ - The MP2RAGE related scripts used in QuIDBBIDS

    • +utils/ - A collection of useful helper tools

    • +workers/ - A library of workers and related functions that constitute the core od the QuIDBBIDS framework

    • private/ - Helper functions that are meant for internal use only

  • dependencies/ - The QuIDBBIDS dependencies as git submodules

  • docs/ - The Sphinx RTD documentation repository

  • tests/ - The collection of (matlab.unittest) test modules for the CI development of QuIDBBIDS

How to contribute code

The preferred way to contribute to the QuIDBBIDS code base or documentation is to use a forking workflow, i.e. fork the dev branch of the main repository, create a feature branch, and submit a pull request for the dev branch. If you are unsure what that means, here is a set-up workflow you may wish to follow:

  1. Fork the project repository on GitHub, by clicking on the “Fork” button near the top of the page — this will create a personal copy of the repository.

  2. Set up a clone of the repository on your local machine and connect it to both the “official” and your copy of the repository on GitHub:

    $ git clone --recurse-submodules -b dev https://github.com/Donders-Institute/quidbbids.git
$ cd quidbbids
$ git remote rename origin official
$ git remote add origin git://github.com/[YOUR_GITHUB_USERNAME]/quidbbids

  3. In case you want to contribute to the RTD documentation, set up a Python virtual environment and install the built dependencies:

    $ python -m venv docs/venv        # Or use any other tool (such as conda)
$ source docs/venv/bin/activate   # On Linux, see the documentation for other operating systems
$ pip install -r docs/requirements.txt

  4. When you wish to start working on your contribution, create a new branch:

    $ git checkout -b [topic_of_your_contribution]

    To update QuIDBBIDS dependencies run:

    $ git submodule update --remote --merge                     # This will update all submodules to their latest commit
$ git submodule update --remote --merge dependencies/spm    # This will update the SPM submodule only

  5. If your work requires a new software dependency that is available as a git repository then you can add it with:

    $ git submodule add -b [BRANCH] [https://REPO_URL/PACKAGE.git] dependencies/[PACKAGE]
$ git commit -m "Add [PACKAGE] submodule in dependencies"

  6. When you are done with coding, you should then test, commit and push your work to GitHub:

    >> runtests('tests')                                   # Run this from the quidbbids directory or use MATLAB's built-in `Test Browser App``
$ docs/make html                                       # For the docs, run this to generate the files locally and open `docs/_build/html/index.html`
$ git commit -am "A SHORT DESCRIPTION OF THE CHANGES"  # Run this every time you have made a set of changes that belong together
$ git push -u origin topic_of_your_contribution        # Run this when you are done and the tox tests are passing

Git will provide you with a link which you can click to initiate a pull request (if any of the above seems overwhelming, you can look up the Git or GitHub documentation on the web)

Coding guidelines

Please check that your contribution complies with the following rules before submitting a pull request:

  • Workers (i.e. +qb/+workers/*Worker.m files that inherit from the Worker class) should have informative help texts and a clear resume with bidsfilters and description. Also, the worker must be described in the Sphinx RTD documentation

  • New methods added to the Coordinator, Manager, or to other classes in +worker should be accompanied with new (matlab.unittest) tests

  • To improve code readability, minor comments can (should) be appended at the end of the code lines they apply to (even if that means right scrolling)

  • Horizontal space is not limited, so multi-line readability is preferred, e.g. the vertical alignment of = operators (i.e. padded horizontally with whitespaces)

  • Vertical space should not be readily wasted to promote better overviews and minimize the need for vertical scrolling