Contributing

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, new test cases, and code fixes. Every contribution helps make SpinLab better for the entire magnetic resonance community.

Ways to Contribute

Report a bug — open an issue on the SpinLab GitHub Issue Tracker
Request a feature — open a feature request on the SpinLab GitHub Issue Tracker
Improve the documentation — fix a typo, expand an example, or add a new guide page
Add a test case — help improve test coverage
Submit a code fix — fix a bug or implement a new feature
Become a maintainer — see the section below

Reporting Bugs and Requesting Features

SpinLab uses the GitHub issue tracker for all bugs and enhancement requests.

When reporting a bug, please include:

A short, self-contained Python snippet that reproduces the problem
The SpinLab version (pip show spinlab)
Your Python version and operating system
What you expected to happen and what actually happened

When requesting a feature, please describe:

What you are trying to accomplish
Why the current functionality does not cover the use case
If possible, a sketch of the desired API

Working with the Code

Setting Up a Development Environment

Fork the repository on GitHub and clone your fork locally:

git clone https://github.com/<your-github-username>/spinlab spinlab-dev
cd spinlab-dev
git remote add upstream https://github.com/SpinLab/spinlab.git

Create a virtual environment with Python 3.10 or higher and install SpinLab in editable mode:

python -m venv venv
source venv/bin/activate        # macOS / Linux
venv\Scripts\activate           # Windows

pip install -e spinlab

Switch to the Development branch, which contains the latest in-progress work:
```
git checkout Development
git pull upstream Development
```

Branching and Committing

Always branch from Development:

git checkout Development
git pull upstream Development
git checkout -b yourname-gh-<issue-number>

Make small, focused commits. After making changes, verify nothing is broken:

python -m pytest

Check for syntax errors and formatting:

python -m flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
python -m black .

Opening a Pull Request

Push your branch to your fork and open a pull request against SpinLab/Development:

git push -u origin yourname-gh-<issue-number>

In your pull request description, briefly explain what the change does and reference the related issue (e.g. Closes #42). Automated checks will run; a maintainer will review and merge once everything passes.

Contributing to the Documentation

The documentation is written in reStructuredText and built with Sphinx. Source files live in the doc/ directory.

To build the docs locally:

cd doc
make html             # macOS / Linux
.\make.bat html       # Windows

The built HTML is written to doc/_build/html/. Open index.html in a browser to preview.

Documentation contributions are especially welcome — if something is unclear, a pull request fixing it is the fastest way to help the whole community.

Becoming a Maintainer

We warmly welcome committed individuals to help maintain SpinLab. You do not need to be a Python expert or a magnetic resonance expert — enthusiasm and reliability matter more. Please reach out to any of the current team members if you are interested.

License

By contributing, you agree that your contributions will be licensed under the MIT License that covers this project.