# Contributing to Daedra
First off, thank you for considering contributing to Daedra! It's people like you that make Daedra such a great tool.
## Code of Conduct
This project and everyone participating in it is governed by our commitment to maintaining a welcoming, inclusive environment. Please be respectful and constructive in all interactions.
## How Can I Contribute?
### Reporting Bugs
Before creating bug reports, please check the existing issues to avoid duplicates. When you create a bug report, include as many details as possible:
- **Use a clear and descriptive title**
- **Describe the exact steps to reproduce the problem**
- **Provide specific examples** (code snippets, commands, etc.)
- **Describe the behavior you observed and what you expected**
- **Include your environment details** (OS, Rust version, etc.)
### Suggesting Enhancements
Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion:
- **Use a clear and descriptive title**
- **Provide a detailed description of the suggested enhancement**
- **Explain why this enhancement would be useful**
- **List any alternatives you've considered**
### Pull Requests
1. **Fork the repository** and create your branch from `main`
2. **Write your code** following our coding standards
3. **Add tests** for any new functionality
4. **Ensure all tests pass** (`cargo test`)
5. **Run linting** (`cargo clippy -- -D warnings`)
6. **Format your code** (`cargo fmt`)
7. **Update documentation** if needed
8. **Submit your pull request**
## Development Setup
### Prerequisites
- Rust 1.91 or later
- Cargo (comes with Rust)
- Git
### Getting Started
```bash
# Clone your fork
git clone https://github.com/YOUR_USERNAME/daedra.git
cd daedra
# Add upstream remote
git remote add upstream https://github.com/dirmacs/daedra.git
# Create a branch for your changes
git checkout -b feature/your-feature-name
# Build the project
cargo build
# Run tests
cargo test
# Run the CLI
cargo run -- --help
```
### Running Tests
```bash
# Run all tests
cargo test
# Run tests with output
cargo test -- --nocapture
# Run specific tests
cargo test search_tests
# Run integration tests (requires network)
cargo test -- integration
# Run benchmarks
cargo bench
```
### Code Style
We use `rustfmt` and `clippy` to maintain consistent code style:
```bash
# Format code
cargo fmt
# Check formatting
cargo fmt -- --check
# Run clippy
cargo clippy -- -D warnings
# Run clippy with all features
cargo clippy --all-features -- -D warnings
```
### Documentation
- All public APIs must have documentation comments
- Use `///` for item documentation
- Use `//!` for module-level documentation
- Include examples in documentation where helpful
```rust
/// Performs a web search using DuckDuckGo.
///
/// # Arguments
///
/// * `args` - Search arguments including query and options
///
/// # Returns
///
/// A `SearchResponse` containing the results
///
/// # Example
///
/// ```rust,no_run
/// use daedra::tools::search::{perform_search, SearchArgs};
///
/// let args = SearchArgs {
/// query: "rust".to_string(),
/// options: None,
/// };
/// let results = perform_search(&args).await?;
/// ```
pub async fn perform_search(args: &SearchArgs) -> DaedraResult<SearchResponse> {
// ...
}
```
### Commit Messages
- Use the present tense ("Add feature" not "Added feature")
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...")
- Limit the first line to 72 characters or less
- Reference issues and pull requests when relevant
Example:
```
Add caching support for search results
- Implement moka-based cache with TTL
- Add cache configuration options
- Add tests for cache operations
Fixes #123
```
### Branch Naming
- `feature/description` - New features
- `fix/description` - Bug fixes
- `docs/description` - Documentation changes
- `refactor/description` - Code refactoring
- `test/description` - Test additions/changes
## Project Structure
```
daedra/
├── src/
│ ├── lib.rs # Library root, public API
│ ├── main.rs # CLI binary
│ ├── server.rs # MCP server implementation
│ ├── types.rs # Type definitions
│ ├── cache.rs # Caching implementation
│ └── tools/
│ ├── mod.rs # Tools module
│ ├── search.rs # Search implementation
│ └── fetch.rs # Page fetching implementation
├── tests/
│ ├── integration_tests.rs # General integration tests
│ └── stdio_transport_tests.rs # STDIO transport & MCP protocol tests
├── benches/
│ └── search_benchmark.rs
├── examples/
│ ├── basic_usage.rs
│ ├── mcp_server.rs
│ └── caching.rs
└── .github/
└── workflows/
├── ci.yml
└── publish.yml
```
## Review Process
1. A maintainer will review your PR
2. They may request changes or ask questions
3. Once approved, your PR will be merged
4. You'll be added to the contributors list!
## Release Process
Releases are managed by maintainers. The process is:
1. Update version in `Cargo.toml`
2. Update `CHANGELOG.md`
3. Create a release tag
4. CI automatically publishes to crates.io
## Questions?
Feel free to open an issue with your question or reach out to the maintainers.
Thank you for contributing! 🎉