Contributing to StrataRouter¶

Thank you for your interest in contributing to StrataRouter! This document provides guidelines for contributions.

Code of Conduct¶

By participating in this project, you agree to abide by our Code of Conduct.

How to Contribute¶

Reporting Bugs¶

Before submitting a bug report: - Check existing GitHub Issues - Verify it's not a known issue in our FAQ - Test with the latest version

Bug Report Template:

**Description:**
Clear description of the bug

**Steps to Reproduce:**
1. Step one
2. Step two
3. Step three

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Environment:**
- StrataRouter version:
- Python version:
- OS:
- Installation method:

**Additional Context:**
Logs, screenshots, etc.

Suggesting Features¶

Feature Request Template:

**Problem Statement:**
What problem does this solve?

**Proposed Solution:**
How should it work?

**Alternatives Considered:**
Other approaches you've thought about

**Additional Context:**
Use cases, examples, etc.

Pull Requests¶

Before You Start¶

Discuss major changes - Open an issue first for significant features
Check existing PRs - Someone might be working on similar changes
Review guidelines - Read this document thoroughly

Development Setup¶

# Clone repository
git clone https://github.com/stratarouter/stratarouter
cd stratarouter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

# Install pre-commit hooks
pre-commit install

# Run tests
pytest

Branch Naming¶

Use descriptive branch names: - feature/add-semantic-cache - New features - fix/route-selection-bug - Bug fixes - docs/update-installation - Documentation - refactor/simplify-router - Refactoring - test/add-integration-tests - Tests

Commit Messages¶

Follow Conventional Commits:

type(scope): subject

body (optional)

footer (optional)

Types: - feat - New feature - fix - Bug fix - docs - Documentation - style - Formatting, no code change - refactor - Code refactoring - test - Adding tests - chore - Maintenance tasks

Examples:

feat(core): add semantic caching support

Implements semantic caching with configurable similarity threshold.
Achieves 85%+ cache hit rate in production workloads.

Closes #123

fix(runtime): correct batch deduplication logic

Previously, similar queries weren't being deduplicated correctly
due to incorrect similarity calculation.

Fixes #456

Code Style¶

Python: - Follow PEP 8 - Use Black for formatting - Maximum line length: 100 characters - Type hints required for public APIs

def route(self, query: str, embedding: np.ndarray) -> RouteResult:
    """Route a query to the best matching route.

    Args:
        query: Input query text
        embedding: Query embedding vector

    Returns:
        RouteResult with matched route and confidence

    Raises:
        ValueError: If embedding dimension doesn't match
    """
    pass

Rust: - Follow Rust style guide - Use rustfmt for formatting - Run cargo clippy before committing

/// Route a query to the best matching route.
///
/// # Arguments
/// * `query` - Input query text
/// * `embedding` - Query embedding vector
///
/// # Returns
/// RouteResult with matched route and confidence
///
/// # Errors
/// Returns error if embedding dimension doesn't match
pub fn route(&self, query: &str, embedding: &[f32]) -> Result<RouteResult> {
    // Implementation
}

Testing¶

Required: - All new features must include tests - Bug fixes must include regression tests - Maintain or improve code coverage (target: 90%+)

Running Tests:

# Python tests
pytest tests/ -v

# Rust tests
cd core
cargo test

cd ../runtime
cargo test

# Integration tests
pytest tests/integration/ -v

# Coverage
pytest --cov=stratarouter --cov-report=html

Test Structure:

def test_feature_behavior():
    """Test that feature works as expected."""
    # Arrange
    router = Router()

    # Act
    result = router.route(query, embedding)

    # Assert
    assert result.route_id == "expected"
    assert result.confidence > 0.8

Documentation¶

Required for: - New features - API changes - Configuration options - Breaking changes

Documentation locations: - Code docstrings (in-code documentation) - docs/ directory (user-facing documentation) - README.md (if relevant to quick start) - CHANGELOG.md (all changes)

Example:

class Router:
    """Semantic router for intelligent query routing.

    The Router uses HNSW indexing and hybrid scoring to route queries
    to the best matching route with sub-millisecond latency.

    Example:
        >>> router = Router(dimension=384)
        >>> router.add_route(Route("billing"))
        >>> result = router.route(query, embedding)
        >>> print(result.route_id)
        'billing'

    Attributes:
        dimension: Embedding vector dimension
        routes: List of registered routes
        config: Router configuration
    """
    pass

Pull Request Template¶

**Description:**
Summary of changes

**Type of Change:**
- [ ] Bug fix (non-breaking)
- [ ] New feature (non-breaking)
- [ ] Breaking change
- [ ] Documentation update

**Checklist:**
- [ ] Tests pass locally
- [ ] Added/updated tests
- [ ] Updated documentation
- [ ] Followed code style guidelines
- [ ] Updated CHANGELOG.md
- [ ] No new warnings

**Related Issues:**
Closes #123

**Screenshots (if applicable):**

**Additional Notes:**

Review Process¶

Automated checks - CI must pass (tests, linting, formatting)
Code review - At least one maintainer approval required
Documentation - Ensure docs are updated
Testing - Verify tests cover new code
Final approval - Maintainer merges

Areas for Contribution¶

High Priority¶

Bug fixes
Documentation improvements
Test coverage improvements
Performance optimization

Good First Issues¶

Look for issues labeled good-first-issue

Feature Ideas¶

Integration with new frameworks
Additional embedding providers
Performance benchmarks
Example applications
Tutorial content

Development Workflow¶

1. Fork & Clone¶

# Fork on GitHub, then:
git clone https://github.com/YOUR_USERNAME/stratarouter
cd stratarouter
git remote add upstream https://github.com/stratarouter/stratarouter

2. Create Branch¶

git checkout -b feature/your-feature-name

3. Make Changes¶

# Write code
# Add tests
# Update docs

4. Test¶

# Run tests
pytest

# Check formatting
black stratarouter
isort stratarouter

# Type checking
mypy stratarouter

5. Commit¶

git add .
git commit -m "feat: add your feature"

6. Push & PR¶

git push origin feature/your-feature-name
# Open PR on GitHub

7. Address Feedback¶

# Make requested changes
git add .
git commit -m "fix: address review comments"
git push origin feature/your-feature-name

Release Process¶

Releases are handled by maintainers:

Update version in pyproject.toml and Cargo.toml
Update CHANGELOG.md
Create release tag: git tag v0.x.0
Push tag: git push --tags
CI automatically builds and publishes to PyPI and crates.io

Getting Help¶

Recognition¶

Contributors are recognized in: - Hall of Fame - Project README - Release notes

License¶

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

Thank you for contributing to StrataRouter!