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. Key required areas of functionality are listed under the issue tracker but the list is not exhaustive.

Contribution of the following is encouraged but optional:

• .py test files
• any 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 or addressed to Sudarshan Ragunathan.

If you would prefer to contribute via email or another mechanism, please contact the task force leads or Sudarshan Ragunathan.

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 functionality.
Further information should be included (e.g. in a readme file or within source code files):

• Identify the component of the DCE/DCE 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 containing the contributor information 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.