Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.

• Code of Conduct
• Getting Started
• Development Setup
• Making Changes
• Testing
• Pull Request Process
• Style Guidelines

This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/constraint-theory-python.git
3. Create a branch: git checkout -b feature/my-feature

• Python 3.8+ (3.11 recommended)
• Rust 1.70+ (for building the native extension)
• pip or poetry for dependency management

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

# Install development dependencies
pip install maturin pytest numpy

# Build the Rust extension in development mode
maturin develop

# Verify installation
python -c "from constraint_theory import PythagoreanManifold; print('OK')"

# Development build (faster compile, slower runtime)
maturin develop

# Release build (slower compile, faster runtime)
maturin develop --release

• feature/ - New features
• fix/ - Bug fixes
• docs/ - Documentation changes
• refactor/ - Code refactoring
• test/ - Adding or modifying tests

Follow conventional commits:

feat: add new batch processing method
fix: correct noise calculation for edge cases
docs: update installation instructions
test: add tests for numpy array input
refactor: simplify manifold initialization

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=constraint_theory --cov-report=html

# Run specific test file
pytest tests/test_bindings.py -v

• Place tests in the tests/ directory
• Name test files with test_ prefix
• Use descriptive test function names

def test_snap_exact_pythagorean_triple():
    """Test that exact Pythagorean triples snap with zero noise."""
    manifold = PythagoreanManifold(density=100)
    sx, sy, noise = manifold.snap(0.6, 0.8)  # 3-4-5 triangle
    assert noise < 0.001, "Exact triple should have near-zero noise"

1. Update Documentation: Ensure README.md and docstrings are updated
2. Add Tests: New features need tests
3. Run Tests: All tests must pass
4. Check Examples: Ensure example scripts still work
5. Submit PR: Use the PR template

• Code follows style guidelines
• Self-review completed
• Comments added for complex logic
• Documentation updated
• Tests added and passing
• No new warnings introduced

• Follow PEP 8
• Use type hints where possible
• Write docstrings for public functions

def process_vectors(
    manifold: PythagoreanManifold,
    vectors: list[tuple[float, float]],
) -> list[tuple[float, float, float]]:
    """Process a list of vectors through the manifold.
    
    Args:
        manifold: The PythagoreanManifold to use.
        vectors: List of (x, y) coordinate pairs.
    
    Returns:
        List of (snapped_x, snapped_y, noise) tuples.
    """
    return manifold.snap_batch(vectors)

• Follow Rust standard formatting (cargo fmt)
• Document public APIs with doc comments
• Run clippy: cargo clippy -- -D warnings

• Open a Discussion
• Check existing Issues

Thank you for contributing!