Contributing Guide#

Thank you for considering contributing to meeg-utils! This document provides guidelines and instructions for contributing.

Development Setup#

Prerequisites#

  • Python 3.11 or higher

  • uv package manager

Installation#

  1. Clone the repository:

git clone https://github.com/colehank/meeg-utils.git
cd meeg-utils

  1. Install dependencies:

uv sync --all-extras --dev

  1. Install pre-commit hooks:

uv run pre-commit install

Development Workflow#

Test-Driven Development (TDD)#

This project follows strict TDD principles:

  1. Write tests first - Always write the test before implementing functionality

  2. Watch it fail (RED) - Run tests to ensure they fail for the right reason

  3. Write minimal code (GREEN) - Implement just enough code to pass the test

  4. Refactor - Clean up code while keeping tests green

See Testing for more details.

Running Tests#

# Run all tests
uv run pytest

# Run specific test file
uv run pytest tests/test_steps/test_steps.py

# Run with coverage
uv run pytest --cov=src/meeg_utils --cov-report=html

Code Quality#

Linting and Formatting#

# Run ruff linter
uv run ruff check src/ tests/

# Auto-fix issues
uv run ruff check --fix src/ tests/

# Format code
uv run ruff format src/ tests/

Type Checking#

# Run mypy
uv run mypy src/

Security Check#

# Run bandit
uv run bandit -r src/ -c pyproject.toml

Pre-commit Hooks#

Pre-commit hooks will automatically run on git commit:

  • Trailing whitespace removal

  • End-of-file fixer

  • YAML/TOML/JSON validation

  • Ruff linting and formatting

To run manually:

uv run pre-commit run --all-files

Pull Request Process#

1. Create a feature branch#

git checkout -b feature/your-feature-name

2. Make your changes#

  • Follow TDD: write tests first

  • Ensure all tests pass

  • Add docstrings to all public functions/classes

  • Update documentation if needed

3. Commit your changes#

git add .
git commit -m "feat: add new feature"

Follow Conventional Commits:

  • feat: new feature

  • fix: bug fix

  • docs: documentation changes

  • style: formatting, missing semicolons, etc.

  • refactor: code refactoring

  • test: adding tests

  • chore: maintenance tasks

4. Push to GitHub#

git push origin feature/your-feature-name

5. Create Pull Request#

  • Go to GitHub and create a pull request

  • Fill in the PR template

  • Link related issues

  • Wait for CI checks to pass

  • Request review

Code Style Guidelines#

Python Style#

  • Follow PEP 8

  • Use type hints for all function signatures

  • Maximum line length: 100 characters

  • Use double quotes for strings

  • Use f-strings for string formatting

Docstrings#

Use NumPy-style docstrings:

def process_data(
    raw: BaseRaw,
    highpass: float = 0.1,
    lowpass: float = 100.0,
) -> BaseRaw:
    """Process MEG/EEG data with filtering.

    Parameters
    ----------
    raw : BaseRaw
        Input raw data.
    highpass : float, optional
        High-pass filter cutoff in Hz. Default is 0.1.
    lowpass : float, optional
        Low-pass filter cutoff in Hz. Default is 100.0.

    Returns
    -------
    BaseRaw
        Processed raw data.

    Examples
    --------
    >>> raw_filtered = process_data(raw, highpass=1.0, lowpass=50.0)
    """

Testing Guidelines#

  • Run the real scientific code, without mocks, on simulated data whose right answer is known (see Testing)

  • Every new step passes meeg_utils.testing.check_step(), every new QC check meeg_utils.testing.check_check()

  • Use descriptive test names: test_<what>_<condition>

  • Use fixtures for common test data

  • Document the source of every default parameter (a paper, or the default of the library it wraps); where there is none, say so

Tutorials#

The tutorials in docs/tutorials/ are Python scripts that sphinx-gallery runs when the documentation is built: text goes in # %% comment blocks (reST), and every figure a block draws appears below it. Each page can be downloaded as a script or a Jupyter notebook.

  • Use MNE’s sample dataset (mne.datasets.sample.data_path()), so the results are real and the tutorials need no other downloads.

  • Keep each tutorial under about five minutes; the documentation build runs all of them (about 15 minutes in total).

  • Run one on its own while writing it: MPLBACKEND=Agg uv run python docs/tutorials/plot_10_quality_control.py.

  • # sphinx_gallery_thumbnail_number = N picks the gallery thumbnail.

Build the documentation with cd docs && uv run make html; a tutorial that raises stops the build.

Reporting Issues#

When reporting issues, please include:

  1. Description: Clear description of the issue

  2. Steps to reproduce: Minimal code example

  3. Expected behavior: What should happen

  4. Actual behavior: What actually happens

  5. Environment:

    • OS and version

    • Python version

    • meeg-utils version

    • Relevant package versions

Feature Requests#

Feature requests are welcome! Please:

  1. Check existing issues first

  2. Clearly describe the use case

  3. Explain why this feature would be useful

  4. Consider if it fits the project scope

Questions?#

License#

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