CONTRIBUTING.md

CONTRIBUTING

pre-commit

This project uses pre-commit, a framework for managing and maintaining git hooks. Pre-commit can be used to manage the hooks that run on every commit to automatically point out issues in code such as missing semicolons, trailing whitespace, and debug statements. By using these hooks, you can ensure code quality and prevent bad code from being uploaded.

To install pre-commit, you can use pip:

pip install pre-commit

After installation, you can set up your git hooks with this command at the root of this repository:

pre-commit install

This will add a pre-commit script to your .git/hooks/ directory. This script will run whenever you run git commit.

For more details on how to configure and use pre-commit, please refer to the official documentation.

Git branches, tags and continuous integration

GitHub Actions builds C-PAC images for each branch and tag pushed to GitHub; these images are pushed to GHCR and deleted upon branch deletion on GitHub.

If a commit is pushed or merged into develop on GitHub, GitHub Actions will push nightly and its variants to Docker Hub.

If a tag is pushed to GitHub that matches the regular expression

^v[0-9]+\.[0-9]+\.[0-9]+$

GitHub Actions will push release-${TAG} and its variants and latest and its variants to Docker Hub.

Software dependencies and variant images

We currently have one main and 3 variant images:

• ABCD-HCP: dependency versions matched to ABCD-HCP BIDS fMRI Pipeline versions
• fMRIPrep-LTS: dependency versions matched to fMRIPrep Long-term support versions
• lite: same dependency versions as main image without FreeSurfer (smaller image)

To save time building Docker images, our continuous integration is set up to build and store staging images independent of changes to C-PAC itself. Images are rebuilt when their Dockerfile changes on a Git branch.

All Dockerfiles are stored in .github/Dockerfiles.

Naming conventions

We have 3 types of staging Dockerfiles: operating system, software dependency, and C-PAC variant.

operating system

{OS name}.{version}.Dockerfile

software dependency

{software name}.{version}-{OS version}.Dockerfile

C-PAC variant

C-PAC.{version}[-{variant}]-{OS version}.Dockerfile (-{variant} is omitted for the main image)

Changing dependencies

• To change a dependency in a C-PAC image, update the stage images at the top of the relevant .github/Dockerfiles/C-PAC.develop-*.Dockerfile.
• If a Dockerfile does not yet exist for the added dependency, create a Dockerfile for the new dependency and add the filename (without extension) to jobs.stages.strategy.matrix.Dockerfile in .github/workflows/build_stages.yml
• If no Dockerfiles use the removed dependency, remove the Dockerfile for the dependency and remove the filename from jobs.stages.strategy.matrix.Dockerfile in .github/workflows/build_stages.yml