Contributing to Paladin

Thank you for your interest in contributing to Paladin! This guide will help you get started with contributing code, documentation, or other improvements.

Code of Conduct
Getting Started
Development Workflow
Architecture Guidelines
Testing Requirements
Documentation Standards
Pull Request Process
Community

Code of Conduct

We follow the Rust Code of Conduct. Please be respectful, inclusive, and professional in all interactions.

Getting Started

Prerequisites

# Install Rust 1.70+
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install development tools
cargo install cargo-watch cargo-audit cargo-llvm-cov

# Clone repository
git clone https://github.com/your-org/paladin.git
cd paladin

# Start development services
make dev

Project Structure

src/
├── core/                    # Domain layer (pure business logic)
├── application/             # Use cases and port definitions
└── infrastructure/          # Adapters for external systems

docs/                        # Documentation
tests/                       # Integration and functional tests
examples/                    # Example code

See docs/architecture/overview.md for detailed architecture.

Development Workflow

1. Create a Feature Branch

git checkout -b feature/your-feature-name

2. Make Changes Following TDD

# 1. Write failing test
cargo test test_new_feature  # Should fail

# 2. Implement feature
# Edit src/...

# 3. Make test pass
cargo test test_new_feature  # Should pass

# 4. Refactor
cargo fmt
cargo clippy

3. Ensure Quality

# Run all checks
make clean-code

# This runs:
# - cargo fmt --check
# - cargo clippy --all-targets --all-features -- -D warnings
# - cargo test --all-features
# - cargo audit

4. Commit with Conventional Commits

git add .
git commit -m "feat: add new Battalion pattern

- Implement Skirmish pattern for ad-hoc agent coordination
- Add configuration builder
- Include integration tests

Closes #123"

Commit Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
refactor: Code refactoring
test: Test additions/changes
chore: Build/tooling changes

5. Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Architecture Guidelines

Hexagonal Architecture Rules

Core Layer (src/core/)
- ✅ Pure business logic
- ✅ Domain entities and value objects
- ❌ No external dependencies
- ❌ No I/O operations
Application Layer (src/application/)
- ✅ Use case implementations
- ✅ Port trait definitions
- ✅ Can import core
- ❌ Cannot import infrastructure
Infrastructure Layer (src/infrastructure/)
- ✅ Adapter implementations
- ✅ External integrations
- ✅ Can import core and application

Naming Conventions

Follow the Medieval Military theme:

Concept	Term	Example
AI Agent	Paladin	`struct Paladin`
Memory	Garrison	`trait GarrisonPort`
Tool	Arsenal/Armament	`struct Arsenal`
Multi-Agent	Battalion	`enum BattalionPattern`
State Persistence	Citadel	`trait CitadelPort`

See docs/architecture/domain-model.md for complete vocabulary.

Design Patterns

Use established patterns consistently:

Builder Pattern: Complex object construction
Port/Adapter Pattern: External dependencies
Repository Pattern: Data persistence
Strategy Pattern: Algorithm variation

See docs/architecture/design-patterns.md for details.

Testing Requirements

Coverage Requirements

Unit Tests: ≥ 80% coverage
Integration Tests: ≥ 70% coverage
Doc Tests: All public APIs

Test Organization

tests/
├── unit/              # Unit tests (fast, no I/O)
├── integration/       # Integration tests (Docker services)
└── functional/        # End-to-end functional tests

Writing Tests

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_paladin_builder() {
        let paladin = PaladinBuilder::new(mock_llm_port())
            .name("Test")
            .system_prompt("You are a tester")
            .build()
            .unwrap();

        assert_eq!(paladin.data.name, "Test");
    }

    #[tokio::test]
    async fn test_paladin_execution() {
        let paladin = create_test_paladin();
        let result = paladin.execute("test input").await.unwrap();
        assert!(!result.content.is_empty());
    }
}
}

Running Tests

# Unit tests
cargo test

# Integration tests
cargo test --features integration-tests

# Specific test
cargo test test_paladin_builder

# With coverage
cargo llvm-cov --html

See docs/contributing/testing-guide.md for complete testing guide.

Documentation Standards

Rustdoc Comments

All public items must have documentation:

#![allow(unused)]
fn main() {
/// Represents an autonomous AI agent.
///
/// A Paladin executes tasks using an LLM backend, maintains conversation
/// history via a Garrison, and can invoke external tools through an Arsenal.
///
/// # Examples
///
/// ```
/// use paladin::PaladinBuilder;
///
/// let paladin = PaladinBuilder::new(llm_port)
///     .name("Assistant")
///     .system_prompt("You are helpful")
///     .build()?;
/// ```
pub struct Paladin {
    // ...
}
}

Module Documentation

#![allow(unused)]
fn main() {
//! Paladin agent execution system.
//!
//! This module provides the core Paladin agent implementation with support
//! for memory (Garrison), tools (Arsenal), and multi-agent coordination (Battalion).

mod paladin;
mod garrison;
}

Markdown Documentation

Use clear section hierarchy (H1 → H2 → H3)
Include code examples
Add diagrams (ASCII art)
Provide troubleshooting sections
Cross-reference related docs

Pull Request Process

PR Checklist

Before submitting, ensure:

Code follows hexagonal architecture
All tests pass (cargo test)
Code is formatted (cargo fmt)
No clippy warnings (cargo clippy)
Documentation updated (rustdoc + markdown)
Examples added/updated if applicable
CHANGELOG.md updated
Commit messages follow conventional format

PR Template

## Description

Brief description of the changes.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing

Describe testing performed:
- Unit tests added/updated
- Integration tests added/updated
- Manual testing steps

## Checklist

- [ ] Tests pass
- [ ] Code formatted
- [ ] Documentation updated
- [ ] CHANGELOG updated

Review Process

Automated Checks: CI must pass
Code Review: At least one approval required
Documentation Review: Check docs are clear
Testing Review: Verify adequate test coverage
Merge: Squash and merge to main

Community

Getting Help

Documentation: See docs/
Issues: GitHub Issues for bugs/features
Discussions: GitHub Discussions for questions
Discord: Join our Discord server (link TBD)

Reporting Bugs

Use this template for bug reports:

**Description**
Clear description of the bug.

**To Reproduce**
Steps to reproduce:
1. Run command...
2. See error...

**Expected Behavior**
What should happen.

**Environment**
- Paladin version:
- Rust version:
- OS:

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

Suggesting Features

Use this template for feature requests:

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

**Proposed Solution**
Describe your solution.

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

**Additional Context**
Examples, mockups, etc.

Specialized Contribution Guides

Adapter Development - Creating new adapters
Testing Guide - Comprehensive testing guide
Provider Integration - Adding LLM providers

Recognition

Contributors are recognized in:

CONTRIBUTORS.md file
Release notes
Project documentation

Thank you for contributing to Paladin! 🛡️

Paladin Framework