Contributing to pyAVS¶

We welcome contributions to pyAVS! This guide will help you get started.

Getting Started¶

Fork the repository on GitHub
Clone your fork locally:

git clone https://github.com/KietzmannLab/pyavs.git
cd pyavs

Set up development environment:

pip install -e ".[dev]"
pre-commit install

Create a branch for your feature:

git checkout -b feature/your-feature-name

Development Workflow¶

Code Style¶

We use several tools to maintain code quality:

Black: Code formatting
Flake8: Linting
isort: Import sorting

Run these before committing:

black pyavs/
flake8 pyavs/
isort pyavs/

Testing¶

Run the test suite:

pytest tests/

# With coverage
pytest --cov=pyavs tests/

Documentation¶

Build documentation locally:

cd docs/
make html

# View in browser
open _build/html/index.html

Types of Contributions¶

Bug Reports¶

When reporting bugs, please include:

Operating system and version
Python version
pyAVS version
Minimal example to reproduce the issue
Full error traceback

Feature Requests¶

Before suggesting new features:

Check if it’s already been requested
Explain the use case clearly
Consider if it fits pyAVS’s scope

Code Contributions¶

Good first issues:

Documentation improvements
Adding examples
Fixing bugs
Adding tests

Major contributions should be discussed in an issue first.

Contribution Guidelines¶

Code Standards¶

Follow PEP 8 style guidelines
Use descriptive variable and function names
Add docstrings to all public functions
Include type hints where appropriate

def load_data(subject_id: int, session: int,
              verbose: bool = True) -> pd.DataFrame:
    """
    Load data for a specific subject and session.

    Parameters
    ----------
    subject_id : int
        Subject identifier
    session : int
        Session number
    verbose : bool, optional
        Whether to print progress (default: True)

    Returns
    -------
    pd.DataFrame
        Loaded data
    """
    # Implementation here
    pass

Documentation Standards¶

Use NumPy-style docstrings
Include examples in docstrings when helpful
Update relevant documentation when adding features
Ensure all public APIs are documented

Testing Standards¶

Write tests for all new functionality
Aim for high test coverage
Use pytest fixtures for setup
Mock external dependencies

import pytest
import pandas as pd
from pyavs.dataloader import load_eye_events

def test_load_eye_events():
    # Test with valid inputs
    result = load_eye_events(subject_id=1, session=1)
    assert isinstance(result, pd.DataFrame)
    assert len(result) > 0

def test_load_eye_events_invalid_subject():
    # Test error handling
    with pytest.raises(ValueError):
        load_eye_events(subject_id=-1, session=1)

Pull Request Process¶

Ensure your code follows the style guidelines
Add or update tests as needed
Update documentation if necessary
Ensure all tests pass
Create a pull request with: - Clear description of changes - Link to related issues - Screenshots if UI changes

Review Process¶

All contributions are reviewed by maintainers:

Code quality and style
Test coverage
Documentation completeness
Compatibility with existing code

Community Guidelines¶

Be Respectful¶

Use welcoming and inclusive language
Be respectful of different viewpoints
Accept constructive criticism gracefully

Be Helpful¶

Help newcomers get started
Share knowledge and experience
Provide constructive feedback

Release Process¶

pyAVS follows semantic versioning:

Major (1.0.0): Breaking changes
Minor (0.1.0): New features, backwards compatible
Patch (0.0.1): Bug fixes, backwards compatible

Development Setup Details¶

Environment Setup¶

Create a conda environment:

conda create -n pyavs-dev python=3.9
conda activate pyavs-dev
pip install -e ".[dev,full]"

Pre-commit Hooks¶

We use pre-commit to run checks automatically:

pre-commit install

# Run manually
pre-commit run --all-files

IDE Setup¶

Recommended VS Code extensions:

Python
Pylance
Black Formatter
Flake8
autoDocstring

Getting Help¶

If you need help:

Check existing documentation
Look at similar implementations in the codebase
Ask questions in GitHub discussions
Contact maintainers directly

Recognition¶

Contributors are recognized in:

README.md contributors section
Documentation acknowledgments

Thank you for contributing to pyAVS! 🧠✨