Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing

Thank you for considering contributing to Zeph.

Getting Started

  1. Fork the repository
  2. Clone your fork and create a branch from main
  3. Install Rust 1.88+ (Edition 2024 required)
  4. Run cargo build to verify the setup

Development

Build

cargo build

Test

# Run unit tests only (exclude integration tests)
cargo nextest run --workspace --lib --bins

# Run all tests including integration tests (requires Docker)
cargo nextest run --workspace --profile ci

Nextest profiles (.config/nextest.toml):

  • default: Runs all tests (unit + integration)
  • ci: CI environment, runs all tests with JUnit XML output for reporting

Integration Tests

Integration tests use testcontainers-rs to automatically spin up Docker containers for external services (Qdrant, etc.).

Prerequisites: Docker must be running on your machine.

# Run only integration tests
cargo nextest run --workspace --test '*integration*'

# Run unit tests only (skip integration tests)
cargo nextest run --workspace --lib --bins

# Run all tests
cargo nextest run --workspace

Integration test files are located in each crate’s tests/ directory and follow the *_integration.rs naming convention.

Lint

cargo +nightly fmt --check
cargo clippy --all-targets

Coverage

cargo llvm-cov --all-features --workspace

Workspace Structure

CratePurpose
zeph-coreAgent loop, config, channel trait
zeph-llmLlmProvider trait, Ollama + Claude + OpenAI + Candle backends
zeph-skillsSKILL.md parser, registry, prompt formatter
zeph-memorySQLite conversation persistence, Qdrant vector search
zeph-channelsTelegram adapter
zeph-toolsTool executor, shell sandbox, web scraper
zeph-indexAST-based code indexing, semantic retrieval, repo map
zeph-mcpMCP client, multi-server lifecycle
zeph-a2aA2A protocol client and server
zeph-tuiratatui TUI dashboard with real-time metrics

Pull Requests

  1. Create a feature branch: feat/<scope>/<description> or fix/<scope>/<description>
  2. Keep changes focused — one logical change per PR
  3. Add tests for new functionality
  4. Ensure all checks pass: cargo +nightly fmt, cargo clippy, cargo nextest run --lib --bins
  5. Write a clear PR description following the template

Commit Messages

  • Use imperative mood: “Add feature” not “Added feature”
  • Keep the first line under 72 characters
  • Reference related issues when applicable

Code Style

  • Follow workspace clippy lints (pedantic enabled)
  • Use cargo +nightly fmt for formatting
  • Avoid unnecessary comments — code should be self-explanatory
  • Comments are only for cognitively complex blocks

License

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