Development Guide¶

This guide covers development setup, building from source, and contributing to tarzi.

Development Setup¶

Prerequisites¶

Rust 1.70 or higher
Python 3.10 or higher
Git
Cargo and pip package managers

Clone and Setup¶

# Clone the repository
git clone https://github.com/mirasurf/tarzi.rs.git
cd tarzi.rs

# Install Rust dependencies
cargo build

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

# Install maturin for Python bindings
pip install maturin

Building from Source¶

Rust Library¶

# Build in debug mode
cargo build

# Build in release mode
cargo build --release

# Run tests
cargo test

# Run with specific features
cargo build --features "full"

Python Bindings¶

# Build Python wheel
maturin build --release

# Install in development mode
maturin develop --release

# Build for specific Python version
maturin build --release --interpreter python3.11

CLI Tool¶

# Build CLI
cargo build --release --bin tarzi

# Install CLI locally
cargo install --path .

Testing¶

Rust Tests¶

# Run all tests
cargo test

# Run specific test
cargo test test_name

# Run integration tests
cargo test --test integration_test_name

# Run with output
cargo test -- --nocapture

Python Tests¶

# Run Python tests
pytest tests/python/

# Run with coverage
pytest tests/python/ --cov=tarzi

# Run specific test file
pytest tests/python/unit/test_converter.py

Documentation¶

Building Docs¶

# Install documentation dependencies
pip install -r docs/requirements.txt

# Build documentation
cd docs
make html

# View documentation
open _build/html/index.html

# Build all formats
make all

Development Workflow¶

Feature Development .. code-block:: bash

# Create feature branch git checkout -b feature/new-feature

# Make changes and test cargo test pytest tests/python/

# Build and test Python bindings maturin develop –release
Documentation Updates .. code-block:: bash

# Update documentation cd docs make html # Check generated docs
Testing Changes .. code-block:: bash

# Run full test suite cargo test pytest tests/python/ cargo clippy cargo fmt –check
Commit and Push .. code-block:: bash

git add . git commit -m “feat: add new feature” git push origin feature/new-feature

Code Style¶

Rust¶

Follow Rust formatting: cargo fmt
Use clippy for linting: cargo clippy
Document public APIs with doc comments
Use meaningful variable and function names

Python¶

Follow PEP 8 style guide
Use type hints for function parameters
Document functions with docstrings
Use meaningful variable names

Contributing¶

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Update documentation
Run the full test suite
Submit a pull request

Issue Reporting¶

When reporting issues, please include:

Operating system and version
Rust/Python versions
Steps to reproduce
Expected vs actual behavior
Error messages and stack traces

Release Process¶

Update version numbers - Cargo.toml - pyproject.toml - docs/conf.py
Update changelog - Add new features and fixes - Note breaking changes
Build and test .. code-block:: bash

cargo build –release maturin build –release cargo test pytest tests/python/
Create release - Tag the release - Upload to crates.io and PyPI - Update documentation