Skip to content

Contributing

Thank you for your interest in contributing to neurospatial! This guide will help you get started.

Getting Started

Development Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally:
git clone https://github.com/YOUR_USERNAME/neurospatial.git
cd neurospatial
  1. Install development dependencies:
uv sync --extra dev
  1. Set up pre-commit hooks:
uv run pre-commit install

Development Workflow

This project uses uv for package management. Always prefix commands with uv run:

# Run tests
uv run pytest

# Run specific test
uv run pytest tests/test_environment.py::test_name -v

# Check code quality
uv run ruff check .

# Format code
uv run ruff format .

# Type check (optional)
uv run mypy src/neurospatial

Code Standards

Python Style

  • Follow PEP 8 (enforced by ruff)
  • Use type hints where practical
  • Write descriptive variable names
  • Keep functions focused and small

Docstring Format

CRITICAL: All docstrings MUST follow NumPy docstring format:

def function_name(param1, param2):
    """
    Short one-line summary ending with a period.

    Longer description if needed.

    Parameters
    ----------
    param1 : type
        Description of param1.
    param2 : type, optional
        Description of param2. Default is None.

    Returns
    -------
    return_type
        Description of return value.

    Raises
    ------
    ValueError
        When this error occurs.

    Examples
    --------
    >>> result = function_name(1, 2)
    >>> print(result)
    3
    """

See NumPy Docstring Guide for details.

Commit Messages

Use Conventional Commits:

feat(environment): add .info() method
fix(regions): correct area calculation for polygons
docs(quickstart): update installation instructions
test(layout): add tests for hexagonal layout
chore(deps): update numpy to 2.3.4

Testing

Writing Tests

  • Place tests in tests/ directory
  • Mirror source structure: src/neurospatial/foo.py → tests/test_foo.py
  • Use descriptive test names: test_environment_from_samples_creates_bins()
  • Use pytest fixtures from tests/conftest.py

Example test:

def test_environment_bin_at_maps_points_correctly():
    """Test that bin_at correctly maps points to bin indices."""
    env = Environment.from_samples(sample_data, bin_size=2.0)
    points = np.array([[10.0, 10.0]])
    bin_idx = env.bin_at(points)
    assert bin_idx.shape == (1,)
    assert 0 <= bin_idx[0] < env.n_bins

Running Tests

# All tests
uv run pytest

# Specific test file
uv run pytest tests/test_environment.py

# With coverage
uv run pytest --cov=src/neurospatial

# Verbose output
uv run pytest -v

# Stop at first failure
uv run pytest -x

Pull Request Process

Before Submitting

  1. Run all tests: uv run pytest
  2. Check code quality: uv run ruff check . && uv run ruff format .
  3. Update documentation: Add/update docstrings and docs pages
  4. Add tests: Ensure new code has test coverage
  5. Update CHANGELOG.md: Add entry under "Unreleased"

Submitting

  1. Create a feature branch:
git checkout -b feature/amazing-feature

  1. Make your changes with clear commit messages

  2. Push to your fork:

git push origin feature/amazing-feature
  1. Open a Pull Request on GitHub

PR Description

Include in your PR description:

  • Summary: What does this PR do?
  • Motivation: Why is this change needed?
  • Testing: How was this tested?
  • Breaking Changes: Any API changes?
  • Related Issues: Link to related issues

Example:

## Summary
Adds `.info()` method to Environment class for printing summary statistics.

## Motivation
Users frequently need to inspect environment properties. This provides
a convenient way to see all key information at once.

## Testing
- Added tests in `test_environment.py`
- Manually tested with various environment types
- All existing tests pass

## Breaking Changes
None

## Related Issues
Closes #42

Documentation

Building Documentation

# Install docs dependencies
uv sync --extra docs

# Serve locally
uv run mkdocs serve

# Build static site
uv run mkdocs build

Documentation is at https://edeno.github.io/neurospatial/

Adding Documentation

  • New features: Update relevant user guide pages
  • API changes: Docstrings are auto-generated
  • Examples: Add Jupyter notebooks to examples/

Release Process

(For maintainers)

  1. Update version in pyproject.toml
  2. Update CHANGELOG.md
  3. Create git tag: git tag v0.2.0
  4. Push tag: git push origin v0.2.0
  5. GitHub Actions handles PyPI release

Getting Help

Code of Conduct

  • Be respectful and inclusive
  • Focus on constructive feedback
  • Help create a welcoming environment

Recognition

Contributors will be acknowledged in:

  • CHANGELOG.md
  • GitHub contributors page
  • Future publications using neurospatial

Thank you for contributing to neurospatial!