11. Contributing#

11.1. Setting up the local development environment#

Fork the https://github.com/juaml/junifer repository on GitHub. If you have never done this before, follow the official guide.
Clone your fork locally as described in the same guide but also add the flag to sync the submodules as well by appending the following to the clone command:
```
... --recurse-submodules
```
Install your local copy into a Python virtual environment. You can read this guide to learn more about them and how to create one.
```
pip install -e ".[dev]"
```
Create a branch for local development using the main branch as a starting point. Use fix, refactor, or feat as a prefix.
```
git checkout main
git checkout -b <prefix>/<name-of-your-branch>
```
Now you can make your changes locally.
Make sure you install git pre-commit hooks like so:
```
pre-commit install
```
When making changes locally, it is helpful to git commit your work regularly. On one hand to save your work and on the other hand, the smaller the steps, the easier it is to review your work later. Please use semantic commit messages.
```
git add .
git commit -m "<prefix>: <summary of changes>"
```
In case, you want to commit some WIP (work-in-progress) code, please indicate that in the commit message and use the flag --no-verify with git commit like so:
```
git commit --no-verify -m "WIP: <summary of changes>"
```
When you’re done making changes, check that your changes pass our test suite. This is all included with tox.
```
tox
```
You can also run all tox tests in parallel. As of tox 3.7, you can run
```
tox --parallel
```

Push your branch to GitHub.

git push origin <prefix>/<name-of-your-branch>

Open the link displayed in the message when pushing your new branch in order to submit a pull request. Please follow the template presented to you in the web interface to complete your pull request.

11.2. GitHub Pull Request guidelines#

Before you submit a pull request, check that it meets these guidelines:

The pull request should include tests in the respective tests directory. Except in rare circumstances, code coverage must not decrease (as reported by codecov which runs automatically when you submit your pull request).
If the pull request adds functionality, the docs should be updated. Consider creating a Python file that demonstrates the usage in examples/ directory.
Make sure to create a Draft Pull Request. If you are not sure how to do it, check here.
Note the pull request ID assigned after completing the previous step and create a short one-liner file of your contribution named as <pull-request-ID>.<type> in docs/changes/newsfragments/, <type> being as per the following convention:
- API change : change
- Bug fix : bugfix
- Enhancement : enh
- Feature : feature
- Documentation improvement : doc
- Miscellaneous : misc
- Deprecation and API removal : removal
For example, a basic documentation improvement can be recorded in a file 101.doc with the content:
```
Fixed a typo in intro by `junifer's biggest fan`_
```
If it’s your first contribution, also add yourself to docs/changes/contributors.inc.
The pull request will be tested against several Python versions.
Someone from the core team will review your work and guide you to a successful contribution.

11.3. Running unit tests#

junifer uses pytest for its unit-tests and new features should in general always come with new tests that make sure that the code runs as intended.

To run all tests

tox -e test

11.4. Adding and building documentation#

Building the documentation requires some extra packages and can be installed by

pip install -e ".[docs]"

To build the docs

cd docs
make local

To view the documentation, open docs/_build/html/index.html.

In case you remove some files or change their filenames, you can run into errors when using make local. In this situation you can use make clean to clean up the already build files and then re-run make local.

Also, we follow British English for the documentation.

11.5. Writing Examples#

The format used for text is reST. Check the sphinx reST reference for more details. The examples are run and displayed in HTML format using sphinx gallery. To add an example, just create a .py file that starts either with plot_ or run_, depending on whether the example generates a figure or not.

The first lines of the example should be a Python block comment with a title, a description of the example, authors and license name.

The following is an example of how to start an example

"""
Generic BIDS datagrabber for datalad.
=====================================

This example uses a generic BIDS datagraber to get the data from a BIDS dataset
store in a datalad remote sibling.

Authors: Federico Raimondo

License: BSD 3 clause
"""

The rest of the script will be executed as normal Python code. In order to render the output and embed formatted text within the code, you need to add a 79 # (a full line) at the point in which you want to render and add text. Each line of text shall be preceded with #. The code that is not commented will be executed.

The following example will create texts and render the output between the texts.

from junifer.datagrabber import PatternDataladDataGrabber
from junifer.utils import configure_logging


###############################################################################
# Set the logging level to info to see extra information
configure_logging(level="INFO")


###############################################################################
# The BIDS datagrabber requires three parameters: the types of data we want,
# the specific pattern that matches each type, and the variables that will be
# replaced in the patterns.
types = ["T1w", "BOLD"]
patterns = {
    "T1w": "{subject}/anat/{subject}_T1w.nii.gz",
    "BOLD": "{subject}/func/{subject}_task-rest_bold.nii.gz",
}
replacements = ["subject"]
###############################################################################
# Additionally, a datalad datagrabber requires the URI of the remote sibling
# and the location of the dataset within the remote sibling.
repo_uri = "https://gin.g-node.org/juaml/datalad-example-bids"
rootdir = "example_bids"

###############################################################################
# Now we can use the datagrabber within a `with` context
# One thing we can do with any datagrabber is iterate over the elements.
# In this case, each element of the datagrabber is one session.
with PatternDataladDataGrabber(
    rootdir=rootdir,
    types=types,
    patterns=patterns,
    uri=repo_uri,
    replacements=replacements,
) as dg:
    for elem in dg:
        print(elem)

###############################################################################
# Another feature of the datagrabber is the ability to get a specific
# element by its name. In this case, we index `sub-01` and we get the file
# paths for the two types of data we want (T1w and bold).
with PatternDataladDataGrabber(
    rootdir=rootdir,
    types=types,
    patterns=patterns,
    uri=repo_uri,
    replacements=replacements,
) as dg:
    sub01 = dg["sub-01"]
    print(sub01)

Finally, when the example is done, you can run it as a normal Python script. To generate the HTML, just build the docs.