CONTRIBUTING.rst

Contributing to BIDScoin

Project organization

• bidscoin/ - The main module with the core libraries and applications, as well as some submodules:
  • bidsapps/ - A package of applications that can process BIDS or BIDS-like data folders
  • cli/ - Argument parsers for generating BIDScoin manpages and Command Line Interfaces (CLI)
  • heuristics/ - Pre-installed template bidsmaps
  • plugins/ - Pre-installed plugins
  • schema/ - Schema files from the BIDS specifications
  • utilities/ - A package of useful helper tools
• docs/ - The Sphinx RTD documentation repository
• tests/ - The collection of (py)test modules for the CI development of BIDScoin

How to contribute code

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

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

1. 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 git://github.com/Donders-Institute/bidscoin
   cd bidscoin
   git remote rename origin official
   git remote add origin git://github.com/[YOUR_GITHUB_USERNAME]/bidscoin
   

2. Set up a virtual environment and install BIDScoin's dependencies:

   python -m venv venv         # Or use any other tool (such as conda)
   source venv/bin/activate    # On Linux, see the documentation for other operating systems
   pip install bidscoin[dev]   # Unfortunately pyproject.toml has no way to install BIDScoin's dependencies only
   pip uninstall bidscoin      # Hence we need to retrospectively remove BIDScoin from site-packages
   # NB: Install dcm2niix yourself (see the online installation instructions)
   

3. When you wish to start a new contribution, create a new branch:

   git checkout -b [topic_of_your_contribution]
   

4. When you are done making the changes you wish to contribute, test, commit and push them to GitHub:

   tox                                                  # Run this command from the bidscoin directory (make sure the venv is activated)
   git commit -am "A SHORT DESCRIPTION OF THE CHANGES"  # Run this command every time you have made a set of changes that belong together
   git push -u origin topic_of_your_contribution        # Run this command 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:

• CLI applications (i.e. Python modules that have an entrypoint + manpage in pyproject.toml) should have informative docstrings and arguments, with usage examples presented as argparse epilogues. All CLIs and plugins must be described in the Sphinx RTD documentation
• Docstrings should be formatted in Sphinx style
• New modules, classes or functionality should be accompanied with type hints and new (py)tests
• All tests performed with tox must pass (python environments may be skipped, if at least one of them is tested)
• Screens are wide nowadays, so the PEP directives for short code lines is considered outdated and does not have to be respected. Otherwise use PEP coding styles
• 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