# Contributing to RAG Module
Thank you for your interest in contributing to the RAG Module! This document provides guidelines and instructions for contributing to the project.
## Table of Contents
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Code Standards](#code-standards)
- [Testing Guidelines](#testing-guidelines)
- [Submitting Changes](#submitting-changes)
- [Release Process](#release-process)
---
## Code of Conduct
This project adheres to professional standards of conduct. Please be respectful and constructive in all interactions.
---
## Getting Started
### Prerequisites
- Rust 1.70 or higher
- Git
- Basic understanding of async Rust and Tokio
- Familiarity with RAG (Retrieval-Augmented Generation) concepts
### Setting Up Development Environment
1. **Clone the repository:**
```bash
git clone https://github.com/escher-dbai/client-rag-rust.git
cd client-rag-rust/rag-module-rust
```
2. **Build the project:**
```bash
cargo build
```
3. **Run tests:**
```bash
cargo test
```
4. **Check code quality:**
```bash
cargo fmt --check
cargo clippy -- -D warnings
```
---
## Development Workflow
### 1. Create a Feature Branch
```bash
# Update main branch
git checkout main
git pull origin main
# Create feature branch
git checkout -b feature/your-feature-name
```
### 2. Make Your Changes
- Write clear, concise commit messages
- Follow the existing code style and conventions
- Add tests for new functionality
- Update documentation as needed
### 3. Before Committing
Run the full check suite:
```bash
# Format code
cargo fmt
# Check for linting issues
cargo clippy -- -D warnings
# Run all tests
cargo test
# Run examples
cargo run --example get_all_documents_example
```
### 4. Commit Your Changes
```bash
# Stage changes
git add .
# Commit with descriptive message
git commit -m "feat: add new feature description"
# Or for bug fixes
git commit -m "fix: resolve issue description"
```
### Commit Message Conventions
Use conventional commit format:
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation only
- `style:` - Code style changes (formatting, etc.)
- `refactor:` - Code refactoring
- `test:` - Adding or updating tests
- `perf:` - Performance improvements
- `chore:` - Maintenance tasks
---
## Code Standards
### Rust Best Practices
1. **Error Handling** - Use `Result` and `?` operator, avoid `.unwrap()` except in tests
2. **Async Code** - Use Tokio for async runtime, follow async best practices
3. **Documentation** - All public items must have `///` doc comments
4. **Type Safety** - Leverage Rust's type system for compile-time guarantees
5. **Memory Safety** - No unsafe code without thorough justification and review
### Code Style
- **Always run `cargo fmt` before committing**
- Follow Rust 2021 edition style guide
- 100 character line limit (soft, enforced by rustfmt)
- Use meaningful variable and function names
- Add inline comments for complex logic
### Documentation Requirements
- Public APIs must have `///` doc comments
- Include examples in doc comments where appropriate
- Update README.md for major changes
- Update docs/ directory for architectural changes
---
## Testing Guidelines
### Test Coverage
- All new features must include tests
- Aim for comprehensive test coverage
- Include both unit tests and integration tests
### Test Types
**Unit Tests:**
```rust
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn test_feature_name() {
// Test implementation
}
}
```
**Integration Tests:**
Located in `examples/` directory as runnable examples.
### Running Tests
```bash
# Run all tests
cargo test
# Run specific test
cargo test test_name -- --exact
# Run with output
cargo test -- --nocapture
# Run only unit tests
cargo test --lib
# Run examples
cargo run --example example_name
```
---
## Submitting Changes
### Pull Request Process
1. **Push your branch:**
```bash
git push origin feature/your-feature-name
```
2. **Create Pull Request:**
- Go to GitHub repository
- Click "New Pull Request"
- Select your branch
- Fill in PR template with:
- Description of changes
- Related issues (if any)
- Testing performed
- Checklist completion
3. **PR Checklist:**
- [ ] Code follows project style guidelines
- [ ] All tests pass (`cargo test`)
- [ ] No clippy warnings (`cargo clippy -- -D warnings`)
- [ ] Code is formatted (`cargo fmt --check`)
- [ ] Documentation is updated
- [ ] CHANGELOG.md is updated (if applicable)
- [ ] New tests added for new features
- [ ] Examples updated (if applicable)
4. **Review Process:**
- Wait for code review
- Address review comments
- Push updates to same branch
- Request re-review if needed
### PR Title Format
Use conventional commit format:
```
feat: add support for custom embeddings
fix: resolve vector search timeout issue
docs: update API documentation
```
---
## Release Process
### Version Numbering
Follow [Semantic Versioning](https://semver.org/):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backward compatible)
- **PATCH**: Bug fixes (backward compatible)
### Creating a Release
**For Maintainers:**
1. **Update version in Cargo.toml:**
```toml
[package]
version = "0.7.0" # Update version
```
2. **Update CHANGELOG.md:**
```markdown
## [0.7.0] - 2026-XX-XX
### Added
- New feature description
### Fixed
- Bug fix description
```
3. **Commit version bump:**
```bash
git add Cargo.toml Cargo.lock CHANGELOG.md
git commit -m "chore: bump version to 0.7.0"
git push origin main
```
4. **Create and push tag:**
```bash
git tag v0.7.0
git push origin v0.7.0
```
5. **Create GitHub Release:**
- Go to GitHub Releases
- Click "Create a new release"
- Select tag: `v0.7.0`
- Title: `Release v0.7.0`
- Description: Copy from CHANGELOG.md
- Publish release
---
## Project Structure
Understanding the codebase structure:
```
rag-module-rust/
├── src/
│ ├── lib.rs # Main RAG module exports
│ ├── types/ # Type definitions
│ ├── config/ # Configuration management
│ ├── db/ # Vector store implementations
│ │ ├── vector_store.rs
│ │ ├── embedded_qdrant.rs
│ │ └── local_file_store.rs
│ └── services/ # Business logic services
│ ├── embedding_service.rs
│ ├── encryption_service.rs
│ ├── document_service.rs
│ └── search_service.rs
├── examples/ # Usage examples
├── docs/ # Documentation
├── tests/ # Integration tests
└── CHANGELOG.md # Version history
```
---
## Feature Areas
### Vector Search
- Embedded Qdrant implementation
- Local file-based vector stores
- Custom distance metrics
### Model Management
- Hugging Face model downloading
- Model caching and loading
- Fallback model system
### Security & Encryption
- AES-256-GCM encryption
- Key management
- Privacy filtering
### Multi-Cloud Support
- AWS estate data processing
- Azure integration
- GCP support
---
## Getting Help
### Resources
- **[README.md](./README.md)** - Quick start guide
- **[CHANGELOG.md](./CHANGELOG.md)** - Version history
- **[docs/](./docs/)** - Detailed documentation
- **[examples/](./examples/)** - Working examples
### Communication
- Open an issue for bugs or feature requests
- Use GitHub Discussions for questions
- Tag maintainers for urgent issues
---
## License
By contributing to this project, you agree that your contributions will be licensed under the MIT License.
---
## Thank You!
Your contributions make this project better. We appreciate your time and effort!