CONTRIBUTING

Contributing to Caxton

Thank you for your interest in contributing to Caxton! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

How to Contribute

Reporting Issues

  • Check if the issue has already been reported
  • Use the issue templates when available
  • Provide a clear description of the problem
  • Include steps to reproduce the issue
  • Mention your environment (OS, Rust version, etc.)

Submitting Pull Requests

  1. Fork the repository and create your branch from main
  2. Follow the code style - Run cargo fmt and cargo clippy
  3. Write tests - Ensure your code has appropriate test coverage
  4. Update documentation - Keep docs in sync with code changes
  5. Use conventional commits - This is required for our release automation

Conventional Commit Format

We use Conventional Commits for all commit messages. This enables automatic changelog generation and semantic versioning.

Format: <type>(<scope>): <subject>

Types:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, etc.)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Test additions or modifications
  • build: Build system changes
  • ci: CI/CD changes
  • chore: Other changes that don’t modify src or test files
  • revert: Revert a previous commit

Examples:

feat(agent): add WebAssembly instance pooling
fix(fipa): correct message routing logic
docs(api): update agent lifecycle documentation
perf(runtime): optimize memory allocation

Development Setup

  1. Install Rust (1.70.0 or later) 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  2. Clone the repository 
    git clone https://github.com/jwilger/caxton.git
cd caxton
  3. Install development tools 
    cargo install cargo-nextest
cargo install cargo-watch
cargo install mdbook
  4. Run tests 
    cargo nextest run
cargo test --doc
  5. Run benchmarks 
    cargo bench

Testing Guidelines

  • Write property-based tests for core domain logic
  • Use integration tests for system behavior
  • Aim for 80% code coverage on core modules
  • Test error paths and edge cases
  • Use testcontainers for external dependencies

Documentation

  • Update rustdoc comments for public APIs
  • Keep architectural decisions in _adrs/ directory
  • Update user guides in docs/ when adding features
  • Include examples in documentation

Release Process

Releases are automated using release-plz:

  1. Automatic PR Creation: When commits land on main, release-plz creates/updates a PR with:
    • Version bumps based on conventional commits
    • Updated CHANGELOG.md
    • Updated Cargo.toml versions

  2. Review and Merge: Maintainers review and merge the release PR

  3. Automatic Release: Upon merge, the system automatically:
    • Creates git tags
    • Publishes to crates.io
    • Creates GitHub releases with binaries
    • Updates documentation

Manual Release (Maintainers Only)

If needed, maintainers can trigger a release manually:

cargo install release-plz
release-plz release

Architecture Guidelines

  • Follow type-driven development principles
  • Make illegal states unrepresentable
  • Use the type system for compile-time guarantees
  • Implement the functional core, imperative shell pattern
  • Ensure all code is observable with structured logging

Getting Help

  • Check the documentation
  • Ask questions in GitHub Discussions
  • Join our community chat (if available)
  • Review existing issues and PRs

Recognition

Contributors will be recognized in:

  • The project README
  • Release notes
  • The contributors page in documentation

Thank you for contributing to Caxton!

Edit this page on GitHub →