Contributing

Contributing to the SML fMRI Preprocessing Template

Welcome!

Thank you for considering contributing to our lab’s fMRI preprocessing pipeline. We created this template to be community-driven, as we believe the best preprocessing practices emerge from collective expertise and rigorous discussion.

How Can I Contribute?

Scientific Contributions

  • Identify potential issues in preprocessing steps

  • Suggest improvements based on recent literature

  • Share knowledge about best practices

  • Question assumptions in our implementation

  • Propose new validation checks

Technical Contributions

  • Bug fixes

  • Code optimization

  • Documentation improvements

  • Example additions

  • Test cases

Contribution Process

  1. Start with an Issue

    • Search existing issues first

    • Create a new issue to discuss your proposed changes

    • Wait for maintainer feedback before significant work

  2. Fork & Create Branch

    • Fork the repository

    • Create a branch for your changes

    • Use clear branch names (e.g., fix-fieldmap-volumes, improve-distortion-correction)

  3. Make Changes

    • Follow existing code style

    • Add comments explaining preprocessing decisions

    • Update documentation as needed

    • Add tests if applicable

    • Use conventional commit messages (see below)

  4. Submit Pull Request

    • Provide clear description of changes

    • Link related issues

    • Include scientific rationale for preprocessing changes

    • Add before/after examples if possible

Pull Request Guidelines

  1. Scientific Validity

    • Explain the scientific rationale for changes

    • Cite relevant literature

    • Describe impact on preprocessing quality

  2. Code Quality

    • Follow Python (PEP 8) and Shell script conventions

    • Include comments explaining preprocessing decisions

    • Maintain existing error checking patterns

    • Add appropriate logging

  3. Documentation

    • Update README (only if needed)

    • Add inline documentation

    • Update parameter descriptions

    • Include clear and generalizable examples

  4. Testing

    • Add validation checks

    • Test with different data types

    • Verify BIDS compliance

    • Check edge cases

Commit Message Guidelines

This project uses Conventional Commits for automated changelog generation and semantic versioning.

Format

<type>(<scope>): <subject>

Types

  • feat: New feature (MINOR version bump)

  • fix: Bug fix (PATCH version bump)

  • docs: Documentation only changes

  • style: Formatting changes (no code change)

  • refactor: Code refactoring

  • perf: Performance improvements

  • test: Adding or updating tests

  • build: Build system changes

  • ci: CI configuration changes

  • chore: Other changes (no src/test changes)

Breaking Changes

Add ! after type or BREAKING CHANGE: in footer for MAJOR version bump:

feat!: remove deprecated API

BREAKING CHANGE: The old API endpoint has been removed.

Examples

Feature:

feat(preprocessing): add multi-echo support

Bug Fix:

fix(fieldmap): correct IntendedFor mapping

Fixes #123

Documentation:

docs: update configuration guide

Release Process

Releases are automated via GitHub Actions:

  1. Commits are analyzed on push to main

  2. Version is determined from commit messages

  3. Changelog is generated automatically

  4. GitHub release is created

See Semantic Versioning for version numbering details.

Questions?

Feel free to:

  • Open an issue for discussion

  • Ask for clarification on existing issues

  • Request more detailed contribution guidelines

We appreciate your help in maintaining high-quality preprocessing standards!

cheers, shawn

Commit Message Guidelines

This project uses Conventional Commits for automated changelog generation and semantic versioning.

Commit Message Format

Each commit message should follow this structure:

<type>(<scope>): <subject>

<body>

<footer>

Types

  • feat: A new feature (triggers MINOR version bump)

  • fix: A bug fix (triggers PATCH version bump)

  • docs: Documentation only changes

  • style: Changes that don’t affect code meaning (formatting, etc.)

  • refactor: Code change that neither fixes a bug nor adds a feature

  • perf: Performance improvements

  • test: Adding or updating tests

  • build: Changes to build system or dependencies

  • ci: Changes to CI configuration files and scripts

  • chore: Other changes that don’t modify src or test files

Breaking Changes

Add ! after the type or BREAKING CHANGE: in the footer to trigger a MAJOR version bump:

feat!: remove deprecated API endpoint

BREAKING CHANGE: The /api/v1/old endpoint has been removed.
Use /api/v2/new instead.

Examples

Feature Addition:

feat(preprocessing): add support for multi-echo fMRI

Implement multi-echo fMRI preprocessing workflow with optimal
combination of echoes using tedana.

Bug Fix:

fix(fieldmap): correct IntendedFor field mapping

Fix issue where fieldmap IntendedFor fields were not properly
updated for runs with non-sequential numbering.

Fixes #123

Documentation:

docs: update configuration guide with new parameters

Add documentation for FMRIPREP_OUTPUT_SPACES and clarify
fieldmap mapping syntax.

Breaking Change:

feat!: update to fMRIPrep 24.0.0

BREAKING CHANGE: Update to fMRIPrep 24.0.0 which requires
different output space syntax. Update settings.template.sh
accordingly.

Scope

Optional, but recommended. Common scopes include:

  • preprocessing

  • fieldmap

  • config

  • workflow

  • docs

  • ci

Release Process

Releases are automated using GitHub Actions. When commits are pushed to the main branch:

  1. The workflow analyzes commit messages

  2. Determines the appropriate version bump (MAJOR, MINOR, or PATCH)

  3. Generates a changelog from commits

  4. Creates a Git tag

  5. Publishes a GitHub release

Manual Release

To manually trigger a release with a specific version bump:

  1. Go to Actions β†’ Release workflow

  2. Click β€œRun workflow”

  3. Select the version bump type (major, minor, or patch)

  4. Click β€œRun workflow”

Version Numbering

This project follows Semantic Versioning:

  • MAJOR version: Incompatible API changes or breaking changes

  • MINOR version: New features in a backwards compatible manner

  • PATCH version: Backwards compatible bug fixes

Development Workflow

1. Fork and Branch

git clone https://github.com/your-username/fmri.git
cd fmri
git checkout -b feat/your-feature-name

2. Make Changes

Follow the contribution guidelines in CONTRIBUTING.md:

  • Write clear, documented code

  • Add tests if applicable

  • Update documentation

  • Use conventional commit messages

3. Test Locally

Test your changes before submitting:

# Test with a single subject
./launch

# Verify BIDS compliance
bids-validator /path/to/test/data

4. Commit Changes

Use conventional commit format:

git add .
git commit -m "feat(preprocessing): add new validation check"

5. Push and Create PR

git push origin feat/your-feature-name

Then create a Pull Request on GitHub with:

  • Clear description of changes

  • Link to related issues

  • Scientific rationale (if applicable)

  • Before/after examples (if applicable)

Code Review Process

  1. Automated checks run on your PR

  2. Maintainers review your changes

  3. Address any feedback

  4. Once approved, your PR will be merged

  5. Release workflow will automatically handle versioning

Changelog Maintenance

The CHANGELOG.md file is automatically updated by the release workflow. You don’t need to manually edit it when contributing.

Documentation

Documentation is built automatically on ReadTheDocs when changes are pushed.

To build documentation locally:

cd docs
pip install sphinx sphinx-rtd-theme myst-parser
make html
open _build/html/index.html

Questions?

  • Open an issue for discussion

  • Ask for clarification on existing issues

  • Contact maintainers through GitHub

We appreciate your contributions to maintaining high-quality preprocessing standards!