Contributing

Welcome to SwissArmyHammer! We appreciate your interest in contributing to this project. This guide will help you get started.

Code of Conduct

SwissArmyHammer follows the Rust Code of Conduct. Please be respectful and inclusive in all interactions.

Getting Started

Development Environment

Install Rust: Ensure you have Rust 1.70 or later installed

Clone the repository:

git clone https://github.com/swissarmyhammer/swissarmyhammer.git
cd swissarmyhammer

Install dependencies:

# Install development dependencies
cargo install cargo-watch cargo-tarpaulin cargo-audit

# Install pre-commit hooks (optional but recommended)
pip install pre-commit
pre-commit install

Run tests to verify setup:

cargo test
cargo clippy
cargo fmt --check

Project Structure

swissarmyhammer/
├── swissarmyhammer/          # Core library
├── swissarmyhammer-cli/      # Command-line interface
├── swissarmyhammer-tools/    # MCP tools and server
├── builtin/                  # Built-in prompts and workflows
├── doc/                      # Documentation (mdBook)
├── tests/                    # Integration tests
└── benches/                  # Benchmarks

How to Contribute

Reporting Issues

Before creating an issue, please:

Search existing issues to avoid duplicates
Use the issue templates when available
Provide detailed information including:
- SwissArmyHammer version (sah --version)
- Operating system and version
- Steps to reproduce
- Expected vs actual behavior
- Relevant configuration files

Proposing Features

For new features:

Open an issue with the “feature request” label
Describe the problem you’re solving
Provide examples of how it would work
Consider implementation complexity
Wait for maintainer feedback before starting work

Code Contributions

Pull Request Process

Fork the repository and create a feature branch
Make your changes following our coding standards
Add tests for new functionality
Update documentation if needed

Run the full test suite:

# Run all tests
cargo test --workspace

# Run integration tests
cargo test --test '*'

# Check formatting and lints
cargo fmt --check
cargo clippy -- -D warnings

# Run benchmarks (if performance-related)
cargo bench

Create a pull request with:
- Clear title and description
- Link to related issues
- Screenshots/examples if applicable
- Checklist of completed items

Coding Standards

Rust Code Style:

Use cargo fmt for formatting
Pass cargo clippy with no warnings
Follow Rust API Guidelines
Write comprehensive doc comments with examples
Use meaningful variable and function names

Error Handling:

Use the anyhow crate for error handling
Provide contextual error messages
Use the Result type consistently
Don’t panic in library code

Testing:

Write unit tests for all public functions
Add integration tests for complex workflows
Use property-based testing where appropriate
Maintain test coverage above 80%

Documentation:

Write rustdoc comments for all public items
Include usage examples in documentation
Update the user guide for new features
Keep CHANGELOG.md updated

Code Review Guidelines

For Authors:

Keep PRs focused and reasonably sized
Respond to feedback promptly
Be open to suggestions and changes
Test edge cases and error conditions

For Reviewers:

Be constructive and specific in feedback
Test the changes locally when possible
Check for security implications
Verify documentation is updated

Documentation Contributions

Documentation improvements are always welcome:

User Guide: Located in doc/src/
API Documentation: Rust doc comments in source code
Examples: Located in doc/src/examples/
README: Project overview and quick start

When updating documentation:

Use clear, concise language
Provide practical examples
Test all code examples
Check for broken links
Follow the existing style and structure

Development Workflows

Running Tests

# Unit tests only
cargo test --lib

# Integration tests only  
cargo test --test '*'

# All tests with verbose output
cargo test --workspace --verbose

# Test with coverage
cargo tarpaulin --out html

# Test specific module
cargo test --package swissarmyhammer search::tests

Development Server

For MCP development:

# Run MCP server in development mode
cargo run --bin swissarmyhammer-cli serve --stdio

# Or with debug logging
SAH_LOG_LEVEL=debug cargo run --bin swissarmyhammer-cli serve --stdio

Benchmarking

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench search

# Generate benchmark reports
cargo bench -- --save-baseline main

Debugging

# Run with debug logging
SAH_LOG_LEVEL=debug cargo run --bin swissarmyhammer-cli prompt list

# Use debugger
RUST_LOG=debug cargo run --bin swissarmyhammer-cli -- --help

# Memory debugging with valgrind
valgrind --tool=memcheck cargo run --bin swissarmyhammer-cli

Contribution Areas

High-Impact Areas

Performance Optimizations
- Search indexing speed
- Template rendering performance
- Memory usage reduction
- Startup time optimization
New Language Support
- Add TreeSitter parsers
- Language-specific prompt templates
- Build tool integrations
MCP Tool Enhancements
- New tool implementations
- Better error reporting
- Request/response validation
Documentation
- More examples and tutorials
- Video guides
- Translation to other languages
Testing
- Edge case coverage
- Performance regression tests
- Cross-platform testing