Contributing¶

We welcome contributions to the IVCAP Service SDK!

Getting Started¶

1. Fork and Clone¶

git clone https://github.com/YOUR_USERNAME/ivcap-service-sdk-python.git
cd ivcap-service-sdk-python

2. Set Up Development Environment¶

poetry install --with dev

3. Create a Branch¶

git checkout -b feature/my-feature

Development Workflow¶

Running Tests¶

poetry run pytest
pytest --cov

Code Quality¶

# Format code
poetry run ruff format .

# Lint
poetry run ruff check . --fix

# Type checking
poetry run pyright

Building Documentation¶

cd docs
pip install -r requirements-docs.txt
mkdocs serve

Visit http://localhost:8000 to preview the docs.

Making Changes¶

Code Changes¶

Make your changes in a feature branch
Add tests for new functionality
Ensure all tests pass: poetry run pytest
Update documentation as needed

Documentation Changes¶

Edit files in docs/docs/
Test locally: mkdocs serve
Check formatting and links
Submit pull request

Commit Messages¶

Use clear, descriptive commit messages:

✨ feat: add new feature
🐛 fix: resolve bug
📝 docs: update documentation
🧪 test: add unit tests
🔨 chore: refactor code

Pull Request Process¶

Update documentation
Add/update tests
Ensure CI passes
Create clear PR description
Link related issues

Code Style¶

We follow Python PEP 8 with these tools:

Ruff — Linting and formatting
Pyright — Type checking
Pytest — Testing

Style Guide¶

# Docstrings follow Google style
def process_job(req: Request, ctx: JobContext) -> Result:
    """
    Process a job.

    Args:
        req: Request to process
        ctx: Job context

    Returns:
        Processing result

    Raises:
        ValueError: If validation fails
    """
    pass

# Type hints required
def add(a: int, b: int) -> int:
    return a + b

# Use meaningful variable names
result = process(data)  # Good
x = process(y)          # Bad

Testing¶

Write tests for new features:

# tests/test_feature.py
import pytest
from src.feature import my_function

def test_my_function_basic():
    result = my_function(5)
    assert result == 10

def test_my_function_error():
    with pytest.raises(ValueError):
        my_function(-1)

Run tests:

poetry run pytest tests/
poetry run pytest tests/test_feature.py -v

Documentation Guidelines¶

Be clear — Write for developers new to the SDK
Include examples — Every concept should have a code example
Link between pages — Use relative links to other docs
Update TOC — If adding new pages, update mkdocs.yml

Reporting Issues¶

Bug Reports¶

Include: - Minimal reproducible example - Expected vs actual behavior - Python version and environment - Traceback (if applicable)

Feature Requests¶

Include: - Use case and motivation - Proposed API/syntax - Any alternatives considered

Questions?¶

GitHub Issues — For bugs and feature requests
Discussions — For questions and ideas
Email — For security issues

License¶

By contributing, you agree that your contributions will be licensed under the same LICENSE as the project.

Thank you for contributing to IVCAP! 🚀