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#

Clone the repository:

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

Install dependencies:

uv sync --all-extras --dev

Install pre-commit hooks:

uv run pre-commit install

Development Workflow#

Test-Driven Development (TDD)#

This project follows strict TDD principles:

Write tests first - Always write the test before implementing functionality
Watch it fail (RED) - Run tests to ensure they fail for the right reason
Write minimal code (GREEN) - Implement just enough code to pass the test
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_preprocessing/test_pipeline.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#

One test file per source file
Use descriptive test names: test_<what>_<condition>
Use fixtures for common test data
Mock expensive operations (trust library implementations)
Aim for >80% code coverage

Reporting Issues#

When reporting issues, please include:

Description: Clear description of the issue
Steps to reproduce: Minimal code example
Expected behavior: What should happen
Actual behavior: What actually happens
Environment:
- OS and version
- Python version
- meeg-utils version
- Relevant package versions

Feature Requests#

Feature requests are welcome! Please:

Check existing issues first
Clearly describe the use case
Explain why this feature would be useful
Consider if it fits the project scope

Questions?#

Open a GitHub Discussion
Check the documentation

License#

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