Contributing

This guide explains how to contribute to EZStitcher.

Setting Up Development Environment

Fork the repository on GitHub

Clone your fork:

git clone https://github.com/your-username/ezstitcher.git
cd ezstitcher

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or
.venv\Scripts\activate     # Windows

Install development dependencies:
```
pip install -e ".[dev]"
```
Install pre-commit hooks:
```
pre-commit install
```

Making Changes

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Make your changes to the codebase
Run tests to ensure your changes don’t break existing functionality:
```
pytest
```
Run linters to ensure your code follows the project’s style guidelines:
```
flake8
black .
isort .
```

Commit your changes with a descriptive commit message:

git add .
git commit -m "Add feature: your feature description"

Push your changes to your fork:

git push origin feature/your-feature-name

Create a pull request from your fork to the main repository

Code Style

EZStitcher follows these code style guidelines:

PEP 8: Follow the PEP 8 style guide
Black: Use Black for code formatting
isort: Use isort for import sorting
Docstrings: Use Google-style docstrings
Type Hints: Use type hints for function and method signatures

Example of a well-formatted function:

def process_image(image: np.ndarray, sigma: float = 1.0) -> np.ndarray:
    """
    Process an image with a Gaussian filter.

    Args:
        image: Input image
        sigma: Standard deviation for Gaussian kernel

    Returns:
        Processed image
    """
    # Convert to float for processing
    image_float = image.astype(np.float32)

    # Apply Gaussian filter
    processed = ndimage.gaussian_filter(image_float, sigma=sigma)

    # Convert back to original dtype
    return processed.astype(image.dtype)

Documentation

All code contributions should include documentation:

Add docstrings to all modules, classes, and functions:

def some_function(param1, param2):
    """
    Brief description of the function.

    Args:
        param1 (type): Description of param1
        param2 (type): Description of param2

    Returns:
        type: Description of return value

    Raises:
        ExceptionType: When and why this exception is raised
    """
    # Function implementation

Update the documentation if you change existing functionality:
```
cd docs
make html
```

Add examples for new features:

# Example usage of new feature
from ezstitcher.core import new_feature

result = new_feature(input_data)
print(result)

Testing

All code contributions should include tests:

Add unit tests for new functionality:

def test_new_feature():
    """Test the new feature."""
    # Test implementation
    result = new_feature(input_data)
    assert result == expected_result

Add integration tests for new components:

def test_new_component_integration():
    """Test the new component in the full pipeline."""
    # Test implementation
    pipeline = Pipeline(new_component)
    result = pipeline.run(input_data)
    assert result == expected_result

Run all tests before submitting a pull request:
```
pytest
```

Pull Request Process

Ensure all tests pass on your local machine
Update the documentation to reflect your changes
Document your changes thoroughly in code and documentation
Submit your pull request with a clear description of the changes
Address any feedback from the code review
Wait for approval from a maintainer

Release Process

Update version number in ezstitcher/__init__.py
Prepare a detailed changelog for the release

Create and push a new tag:

git tag -a v{version} -m "Release version {version}"
git push origin v{version}

Build and upload the package to PyPI manually:

# Build the package
python -m build

# Upload to PyPI (you'll need your PyPI token)
python -m twine upload dist/*

Note: Make sure you have build and twine installed: pip install build twine

Code of Conduct

Please follow these guidelines when contributing to EZStitcher:

Be respectful of other contributors
Be constructive in your feedback
Be patient with new contributors
Be inclusive and welcoming to all
Be collaborative and work together to solve problems