Contributing to MicroDC Worker¶

Thank you for your interest in contributing to the MicroDC Worker project! This guide will help you get started.

Quick Start¶

1. Set Up Development Environment¶

# Clone the repository
git clone <repository-url>
cd microhub_worker

# Install with dev dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks (recommended)
pip install pre-commit
pre-commit install

2. Run Tests¶

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

3. Code Quality Checks¶

# Format code
python -m black src/ tests/ --line-length 100

# Lint code
python -m ruff check src/ tests/ --fix

# Type check
python -m mypy src/ --ignore-missing-imports

Development Workflow¶

1. Create a Feature Branch¶

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

2. Make Your Changes¶

Write clear, concise code following existing patterns
Add type hints to all function signatures
Write docstrings for public functions
Follow PEP 8 style guide (enforced by Black)

3. Write Tests¶

Add tests for new functionality
Aim for >80% coverage for new code
Run tests locally before committing

python -m pytest tests/test_your_module.py -v

4. Commit Your Changes¶

# Pre-commit hooks will run automatically
git add .
git commit -m "feat: add new feature description"

# Or if hooks are not installed
python -m black src/ tests/
python -m ruff check src/ tests/ --fix
git commit -m "feat: add new feature description"

Commit Message Format¶

We follow Conventional Commits:

feat: - New feature
fix: - Bug fix
docs: - Documentation changes
test: - Adding or updating tests
refactor: - Code refactoring
perf: - Performance improvements
style: - Code style changes (formatting)
chore: - Maintenance tasks

Examples:

feat: add support for vLLM engine
fix: resolve timeout error in long-running jobs
docs: update configuration guide
test: add tests for job executor

Code Standards¶

Python Style¶

Line length: 100 characters (Black default)
Imports: Sorted with isort (black profile)
Type hints: Required for all public functions
Docstrings: Google style for public APIs

Testing Guidelines¶

Test location: tests/test_<module>.py
Test naming: test_<functionality>_<scenario>
Async tests: Use @pytest.mark.asyncio decorator
Mocking: Use unittest.mock or pytest-mock
Coverage: Aim for >80% for new code

Example test:

import pytest
from src.core.config import WorkerConfig

class TestWorkerConfig:
    """Test WorkerConfig class."""

    def test_default_config_loading(self):
        """Test loading default configuration."""
        config = WorkerConfig()
        config.load()

        assert config.get("worker.organization") == "default"
        assert config.get("server.timeout") == 30

Type Hints¶

from typing import Optional, List, Dict, Any

def process_job(
    job_id: str,
    parameters: Dict[str, Any],
    timeout: Optional[int] = None
) -> Dict[str, Any]:
    """Process a job with given parameters.

    Args:
        job_id: Unique identifier for the job
        parameters: Job parameters dictionary
        timeout: Optional timeout in seconds

    Returns:
        Dictionary containing job results

    Raises:
        JobExecutionError: If job processing fails
    """
    # Implementation
    pass

Project Structure¶

microhub_worker/
├── src/
│   ├── api/            # API models and server communication
│   ├── core/           # Core client logic and configuration
│   ├── engines/        # Inference engine implementations
│   ├── jobs/           # Job execution and queue management
│   ├── models/         # Model registry and capabilities
│   ├── processors/     # Document processing
│   └── utils/          # Utilities and helpers
├── tests/              # Test suite
├── config/             # Configuration files
├── docs/               # Documentation
└── tools/              # Development scripts

Adding New Features¶

Adding a New Engine¶

Create engine class inheriting from InferenceEngine or ProcessingEngine
Implement required abstract methods
Add configuration to config/default.yaml
Register engine in src/core/client.py
Add tests in tests/test_<engine_name>.py
Update documentation

See src/engines/ollama.py for reference implementation.

Adding New Configuration Options¶

Add to config/default.yaml with environment variable support
Update src/core/config.py if needed
Add validation in validate() method
Document in README.md or relevant docs
Add tests for new configuration

Documentation¶

Where to Document¶

README.md: User-facing features and quick start
docs/TODO.md: Development progress and roadmap
docs/CODE_QUALITY.md: Development tools and standards
Inline docstrings: Public APIs and complex logic
Code comments: Non-obvious implementation details

Documentation Style¶

Use Google-style docstrings
Include examples for complex functions
Document exceptions that may be raised
Keep examples up to date with code changes

Getting Help¶

Resources¶

Code Quality Guide: docs/CODE_QUALITY.md
Development TODO: docs/TODO.md
Authentication Guide: docs/AUTHENTICATION.md
Document Processing: docs/DOCUMENT_PROCESSING_INTEGRATION.md

Questions or Issues?¶

Open an issue on GitHub
Check existing issues for similar problems
Provide detailed information about your setup
Include error messages and logs

Testing Your Changes¶

Local Testing¶

# Run all tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_config.py -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=term-missing

# Run integration tests (requires server)
python -m pytest tests/integration/ -v

Development Tools¶

# Development server with auto-reload
./tools/run.sh -w

# Interactive testing menu
./tools/test_worker.sh

# Check code quality
python -m black src/ tests/ --check
python -m ruff check src/ tests/
python -m mypy src/

Pull Request Process¶

Update tests: Ensure all tests pass
Update documentation: Update README.md and docs/TODO.md
Code quality: Run all quality checks
Coverage: Maintain or improve test coverage
Commit messages: Follow conventional commits format
Description: Provide clear PR description with context

PR Checklist¶

[ ] Tests added/updated and passing
[ ] Documentation updated (README.md, docs/TODO.md)
[ ] Code formatted with Black
[ ] Linting passes (Ruff)
[ ] Type hints added
[ ] No security issues (Bandit)
[ ] Coverage maintained or improved

Release Process¶

Version bumping is automated:

Every commit auto-increments PATCH version (0.1.0 → 0.1.1)
Manual bumps for MINOR/MAJOR versions:

./tools/bump_version.py minor  # 0.1.5 → 0.2.0
./tools/bump_version.py major  # 0.9.0 → 1.0.0

See docs/VERSIONING.md for details.

Code of Conduct¶

Be respectful and inclusive
Provide constructive feedback
Focus on the code, not the person
Help others learn and grow

License¶

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to MicroDC Worker! 🚀