Skip to content

Development Overview

Introduction

This guide provides essential information for developers who want to contribute to Rivusio or build extensions using its framework. It covers development setup, coding standards, testing practices, and contribution workflows.

Development Environment

Prerequisites

  • Python 3.10 or higher
  • Poetry for dependency management
  • Git for version control
  • Make (optional, but recommended)

Initial Setup

# Clone the repository
git clone https://github.com/zbytealchemy/rivusio.git
cd rivusio

# Install dependencies
poetry install

# Install pre-commit hooks
poetry run pre-commit install

Project Structure

rivusio/
├── src/
│   └── rivusio/
│       ├── core/          # Core framework components
│       ├── streams/       # Stream processing
│       ├── monitoring/    # Metrics and monitoring
│       └── plugins/       # Plugin system
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── docs/                 # Documentation
├── examples/            # Example code
└── scripts/            # Development scripts

Development Workflow

1. Code Style

We follow strict coding standards:

  • Black for code formatting
  • isort for import sorting
  • mypy for type checking
  • ruff for linting
# Format code
make format

# Run linting
make lint

# Type checking
make typecheck

2. Testing

All code changes must include tests:

# Run unit tests
make test-unit

# Run integration tests
make test-integration

# Run all tests with coverage
make coverage

3. Documentation

Documentation is crucial:

  • Update API documentation for new features
  • Include docstrings for all public APIs
  • Add examples for new functionality
  • Update architecture docs for significant changes
# Build documentation
make docs

# Serve documentation locally
make docs-serve

Development Guidelines

1. Type Safety

  • Use type hints consistently
  • Leverage Pydantic for data validation
  • Run mypy checks before committing
from typing import Dict, List
from pydantic import BaseModel

class ConfigModel(BaseModel):
    name: str
    values: List[int]
    options: Dict[str, str]

2. Error Handling

  • Use custom exception types
  • Provide meaningful error messages
  • Include error context
from rivusio.core.exceptions import PipelineError

class ValidationError(PipelineError):
    """Raised when data validation fails."""
    def __init__(self, message: str, context: dict):
        super().__init__(f"{message}: {context}")
        self.context = context

3. Testing Practices

  • Write unit tests for all new code
  • Include integration tests for features
  • Use fixtures for common test data
  • Mock external dependencies
import pytest
from rivusio.core import Pipeline

@pytest.fixture
def sample_pipeline():
    return Pipeline()

def test_pipeline_processing(sample_pipeline):
    result = sample_pipeline.process({"data": "test"})
    assert result.status == "success"

4. Performance Considerations

  • Profile code changes
  • Consider memory usage
  • Test with large datasets
  • Document performance implications

Contribution Process

  1. Feature Planning
  2. Discuss new features in issues
  3. Get feedback on implementation

  4. Review existing solutions

  5. Implementation

  6. Create feature branch
  7. Follow coding standards
  8. Add tests and documentation

  9. Update changelog

  10. Code Review

  11. Submit pull request
  12. Address review feedback

  13. Update based on CI results

  14. Release Process

  15. Version bumping
  16. Changelog updates
  17. Documentation updates
  18. Release notes

Plugin Development

1. Plugin Structure

from rivusio.plugins import Plugin, PluginConfig

class CustomPlugin(Plugin):
    """Custom plugin implementation."""
    def __init__(self, config: PluginConfig):
        super().__init__(config)

2. Plugin Registration

from rivusio.plugins import register_plugin

@register_plugin
class MyPlugin(Plugin):
    """Automatically registered plugin."""

Debugging and Profiling

1. Debugging Tools

  • Built-in debugger support
  • Logging configuration
  • Performance profiling
  • Memory profiling

2. Monitoring

from rivusio.monitoring import Monitor

monitor = Monitor()
monitor.track_performance()

Additional Resources

Getting Help

  • GitHub Issues for bug reports
  • Discussions for questions
  • Pull Requests for contributions
  • Documentation for guidance

Remember to check the Contributing Guide for detailed information about the contribution process and coding standards.