Contributing to SemanticLens¶

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

Development Setup¶

Fork and clone the repository:

git clone https://github.com/yourusername/semanticlens.git
cd semanticlens

Install in development mode:
```
uv sync --dev
```
Install pre-commit hooks (optional but recommended):
```
pre-commit install
```

Code Style¶

SemanticLens uses several tools to maintain code quality:

Ruff for linting and formatting
pytest for testing
NumPy style docstrings for documentation

Run the linter before submitting:

ruff check .
ruff format .

Testing¶

Run the test suite to ensure your changes don’t break existing functionality:

# Run all tests
pytest

# Run with coverage
pytest --cov=semanticlens

# Run specific test file
pytest tests/test_lens.py

Writing Tests¶

When adding new features, please include tests:

# tests/test_new_feature.py
import pytest
from semanticlens import YourNewClass

def test_your_new_feature():
    instance = YourNewClass()
    result = instance.your_method()
    assert result == expected_value

Documentation¶

Documentation is built with Sphinx. To build docs locally:

cd docs
make html

# View docs
open build/html/index.html

Docstring Guidelines:

Use NumPy style docstrings
Include parameter types and descriptions
Add examples for public APIs
Document return values and exceptions

def your_function(param1: str, param2: int = 10) -> bool:
    """Brief description of the function.

    Longer description with more details about what the function
    does and how to use it.

    Parameters
    ----------
    param1 : str
        Description of the first parameter.
    param2 : int, optional
        Description of the second parameter (default is 10).

    Returns
    -------
    bool
        Description of what is returned.

    Examples
    --------
    >>> result = your_function("example", 5)
    >>> print(result)
    True
    """
    return True

Submitting Changes¶

Create a new branch for your feature:

git checkout -b feature/your-feature-name

Make your changes and commit:

git add .
git commit -m "Add your descriptive commit message"

Push to your fork:

git push origin feature/your-feature-name

Create a Pull Request on GitHub with: - Clear description of changes - Reference to any related issues - Screenshots/examples if applicable

Types of Contributions¶

We welcome several types of contributions:

Bug Fixes: Found a bug? Please report it in the GitHub issues or submit a fix.
New Features: Have an idea for a new component visualizer or foundation model integration? Open an issue to discuss it first.
Documentation: Improvements to docs, tutorials, or examples are always appreciated.
Performance Improvements: Optimizations to existing code are welcome.
Tests: Additional test coverage helps ensure reliability.

Code Review Process¶

All submissions go through code review:

Automated checks (tests, linting) must pass
At least one maintainer will review your code
You may be asked to make changes
Once approved, your code will be merged

Guidelines for Good PRs¶

Keep changes focused - one feature/fix per PR
Write descriptive commit messages
Add tests for new functionality
Update documentation if needed
Follow the existing code style
Be responsive to review feedback

Reporting Issues¶

When reporting bugs or requesting features:

Check existing issues first
Use the issue templates if available
Provide minimal reproducible examples
Include environment details (Python version, OS, etc.)

Community Guidelines¶

Be respectful and inclusive
Help others learn and contribute
Focus on constructive feedback
Follow the project’s code of conduct

Getting Help¶

If you need help:

Open a GitHub issue for bugs or feature requests
Check the documentation and tutorials
Look at existing code for examples
Ask questions in discussions

Thank you for contributing to SemanticLens! 🔍