How to contribute code

OSIPI Taskforce 2.3 exists to collect source code from members of the perfusion community. We invite colleagues to contribute source code for performing one or more DCE-MRI or DSC-MRI processing steps.

What is a code contribution?

Currently, we are inviting contributions of source code files written in Python. Contributions are welcome, regardless of whether they duplicate functionality already present in the repository.

Contribution of the following is encouraged but optional:

• .py test files
• test data
• files containing other relevant data or information, e.g. typical real-world applications of code, scripts, known features and limitations, citations etc.

How do I contribute code (in a nutshell)?

Code can be contributed using Git. Briefly:

• Create a new feature branch from the develop branch. The branch name should begin with your initials followed by the institute abbreviation, e.g. SR_BNI_CodeContribution
• Add the files
• Submit a pull request to merge the branch back into develop

Queries regarding code submission can be submitted using the label 'question' on the issue tracker. If you would prefer to contribute via email or another mechanism, please contact the task force leads.

See below for detailed instructions on contributing code via Git.

How should my code contribution be structured?

To help facilitate an organized approach to housing community-contributed source code, we ask contributors to submit their source code in the following location:

src/original/<initials>_<institution><country>, e.g. src/original/ST_SydneyAus

Within this folder, the structure is up to you and you may include multiple types of perfusion functionality.
Further information can be included (e.g. in a readme file or within source code files):

• Identify the component of the DCE/DSC pipeline that the code is intended to represent
• Name of author(s)
• Name of the contributor's institution / organization
• Name of the contributor's lab / research group (if applicable)

How to submit code using Git

Code submission can be performed directly to the repository by creating a feature branch as described above. For contributors who are not familiar with Git syntax, we recommend using Github Desktop, which allows the above steps to be carried out easily.

Briefly:

• Clone the repository from github.com to your local machine
• Create your new feature branch on your local machine
• Add your code to this branch and commit the changes
• Push the new branch to github.com
• On github.com, select the Pull Requests tab and click on New pull request. For base select the develop branch and under compare select your feature branch. Click on create pull request.

Alternatively, code can be submitted using command-line Git, as follows:

Installing Git

To install a fresh copy of Git or to upgrade to the latest version, please follow the instructions outlined in: Installing Git

Clone repo and switch to develop branch

$git clone https://github.com/OSIPI/DCE-DSC-MRI_CodeCollection.git
$git switch develop
$git status

Git status should say that you are now on branch develop.

Create new feature branch

$git checkout -b <initials_featurebranchname>

Add contributions to feature branch (in folder src/original/<initials>_<institution><country>)

Push feature branch to remote

$git add <all_untracked_files>
$git commit -m "Commit Message"
$git push -u origin <feature_branch_name>

In GitHub, make a pull request from your new feature branch to develop for approval.

On github.com, select the Pull Requests tab and click on New pull request. . In the drop-down for base select the develop branch and under compare select the branch with your commits. Click on create pull request.

Workflow of new contributions

The figure below summarizes the steps involved when a new contribution is added. First the contributor (or alternatively the TF member) adds the code as described above. When this is done, the test files can be created. If there is already test code and data available from other contributions, adding the tests files will be relatively straightforward. If not, suitable test data needs to be added and a test file needs to be created. To be able to update the notebooks, we need to add the contribution and some specific details to the results-meta.json file. The rest of the steps are performed automatically once the branch is merged with develop. If a notebook for this specific functionality is already, the results of the new contribution will be added automatically to the figures. If not, a new notebook needs to be created by one of the TF members.