Contributing to `openretina`

We welcome contributions to openretina! This guide will help you get started with contributing to the project, whether you're fixing bugs, adding features, improving documentation, or adding new models and datasets.

How to Contribute

Types of Contributions

We appreciate the following types of contributions:

Bug reports: Report issues you encounter
Feature requests: Suggest new features or improvements
Documentation improvements: Fix typos, add examples, or improve explanations
New models: Implement new neural network architectures
New datasets: Add support for additional retinal datasets
Code improvements: Optimize performance, improve code quality
Tests: Add or improve test coverage

Getting Started

Fork the repository on GitHub

Clone your fork to your local machine:

git clone git@github.com:yourusername/open-retina.git
cd open-retina

Create a new branch for your contribution:

git checkout -b feature/your-feature-name

Development Environment Setup

Install the package in development mode: Preferred (uv, matches project Makefile):
```
uv sync --extra dev
```
Alternative (pip):
```
pip install -e ".[dev]"
```
This installs openretina with all development dependencies including:
ruff for linting and formatting
mypy for type checking
pytest for testing
pre-commit for notebook commit hooks
jupyterlab for notebook development
Install notebook commit hooks once per clone:
```
uv run pre-commit install
# With the pip environment activated instead:
# pre-commit install
```
make install-dev performs both the uv installation and hook setup.

For model development, also install:

uv sync --extra devmodels
# or:
pip install -e ".[devmodels]"

Development Workflow

Before submitting any changes, please follow this workflow:

Make your changes following our code style guidelines

Run the development checks:

# Fix code formatting
make fix-formatting

# Run all tests (type checks, code style, unit tests)
make test-all

Test your changes thoroughly:
Ensure existing tests pass
Add new tests for new functionality, if possible
Test with different datasets if applicable
Update documentation if needed:
Update docstrings for new functions/classes
Update user-facing documentation
Add examples for new features

Submitting Changes

Commit your changes with descriptive commit messages:

git add .
git commit -m "Add feature: brief description of what you added"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub with:
A clear title and description
Reference to any related issues
List of changes made
Any breaking changes highlighted

Guidelines for Specific Contributions

Notebooks

Keep maintained tutorials and examples in Git, with saved outputs, execution counts, and widget state cleared. Each notebook must be at most 1 MiB after cleaning. Store large generated figures, videos, datasets, and executed reports outside Git and link to them when needed. The size limit also catches large attachments or data embedded in notebook source that output stripping cannot remove.

The pre-commit hooks run when you commit. If nbstripout changes a notebook, the commit stops so you can review the cleanup, stage the file again, and retry. The hook also clears outputs in your local notebook file. Save any results you need separately before committing. Code and Markdown cells are retained.

To clean and check all tracked notebooks manually:

make check-notebooks
# With a pip environment instead:
# pre-commit run --all-files

A run that changes files reports failure; review the changes and rerun to confirm that all checks pass. These checks do not execute notebooks or download datasets. They cover all tracked notebooks, including those excluded from execution tests.

The Notebook hygiene GitHub Actions workflow runs the same hooks on pull requests and pushes to main. CI fails if a notebook needs cleaning or exceeds the size limit; it does not commit fixes back to the branch. Contributors who skipped the local hooks can run the command above to fix their files.

Maintainer setup on GitHub

After this workflow is published, configure branch protection or a ruleset for main to require pull requests and the notebook-hygiene status check, without routine bypasses. The workflow file alone does not make the check mandatory.

Use squash merging to bring only the final cleaned notebook state into main. If using merge commits or rebase merging, remove oversized notebook versions from the PR's individual commits first: a later cleanup commit does not remove the earlier large version from history. CI checks the current files, not every commit.

CI runs after upload, so it cannot prevent a large file from reaching a feature branch. Squash merging does not erase objects already uploaded to other branches or retained GitHub references, and these checks do not shrink existing Git history.

Adding New Models

When contributing new model architectures:

Follow the existing structure:
Implement models in openretina/models/
Use PyTorch Lightning for training logic
Follow naming conventions for consistency
Include comprehensive documentation, if you can:
Docstrings for all classes and methods
Example usage in documentation
Reference to original paper where the method is coming from, if applicable
Add tests:
Unit tests for model components
Integration tests for training/inference

Adding New Datasets

When adding support for new datasets:

Implement in openretina/data_io/:
Create a new subdirectory for your dataset
Implement data loaders following the base classes
Include stimulus and response handling
Follow data conventions:
Use consistent data formats across datasets
Include proper metadata handling
Provide examples:
Add example usage in documentation
Include data format specifications
Provide download instructions if data is publicly available, or add it to our HuggingFace

Documentation Guidelines

When contributing to documentation:

Use clear, concise language
Include code examples where applicable
Follow the existing documentation structure
Update the navigation in mkdocs.yml if adding new pages
Test documentation builds locally before submitting

For detailed documentation standards, see our documentation writing guidelines below.

Testing

Running Tests

# Run all tests
make test-all

# Run specific test categories
make test-types        # Type checking with mypy
make test-codestyle    # Code style with ruff
make test-formatting   # Code formatting with ruff
make test-unittests    # Unit tests with pytest

# Test notebooks
make test-notebooks

Writing Tests

Write unit tests for all new functions and classes
Use pytest for test framework
Place tests in the tests/ directory
Follow existing test structure and naming conventions
Include both positive and negative test cases
Test edge cases and error conditions

Documentation Writing Guidelines

When writing or updating documentation:

General Principles

Be accurate: Always reflect the actual code behavior
Be complete: Provide all necessary information for users
Be clear: Use simple, direct language
Be consistent: Follow established patterns and terminology
Include examples: Show don't just tell

Docstring Standards

Use Google-style docstrings for all public functions and classes. Do not use Sphinx-style (:param, :returns:) or NumPy-style formats. See the code style guide for full details.

def example_function(param1: int, param2: str = "default") -> bool:
    """Brief description of what the function does.

    Longer description if needed. Explain the purpose, behavior,
    and any important details.

    Args:
        param1: Description of the first parameter.
        param2: Description of the second parameter with default value.

    Returns:
        Description of what the function returns.

    Raises:
        ValueError: When and why this exception is raised.

    Example:
        >>> result = example_function(42, "test")
        >>> print(result)
        True
    """

API Documentation

For API reference pages:

Use mkdocstrings for automatic documentation generation
Include module-level documentation explaining the purpose
Group related functions/classes logically
Provide usage examples for complex APIs

Tutorial Documentation

For tutorials and guides:

Start with clear objectives: What will the user learn?
Provide complete, runnable examples
Explain each step and why it's necessary
Include expected outputs where helpful
Address common issues and troubleshooting

Code Examples

Always test code examples to ensure they work
Use realistic data in examples when possible
Show imports and setup required
Keep examples focused on the specific concept being demonstrated

Code Review Process

All contributions require review before merging
Address all feedback before expecting merge
Maintain backwards compatibility unless explicitly breaking changes
Update version numbers appropriately for significant changes

Getting Help

If you need help with contributing:

Check existing documentation first
Open an issue on GitHub for bugs or feature requests
Join discussions in existing issues and pull requests
Contact maintainers if you have questions about the contribution process

Recognition

Contributors are recognized in:

The project's contributor list, and Zenodo's software reference.
Release notes for significant contributions
Academic publications when appropriate

Thank you for contributing to openretina!

Contributing to openretina