# Contributing to Vyctor
Thank you for your interest in contributing to Vyctor! This document provides guidelines and instructions for contributing.
## Code of Conduct
Please be respectful and constructive in all interactions. We welcome contributors of all experience levels.
## Getting Started
### Prerequisites
- Rust 1.70+ (install via [rustup](https://rustup.rs/))
- DuckDB VSS extension (automatically installed on first run)
### Development Setup
1. Clone the repository:
```bash
git clone https://github.com/antonmagnus/vyctor.git
cd vyctor
```
2. Build the project:
```bash
cargo build
```
3. Run tests:
```bash
cargo test
```
4. Build with local embeddings support (default):
```bash
cargo build --features local-embeddings
```
### Project Structure
```
vyctor/
├── src/
│ ├── cli/ # CLI command implementations
│ ├── config/ # Configuration schema and loading
│ ├── embeddings/ # Embedding providers (local, OpenAI, Voyage)
│ ├── indexer/ # File walking, chunking, and indexing
│ ├── reranker/ # Reranking providers
│ ├── search/ # Search engine implementation
│ ├── storage/ # DuckDB storage layer
│ ├── daemon.rs # Background watcher daemon
│ ├── lib.rs # Library exports
│ └── main.rs # CLI entry point
├── tests/ # Integration tests
└── models/ # Local model configuration
```
## Making Changes
### Workflow
1. **Fork** the repository
2. **Create a branch** for your feature or fix:
```bash
git checkout -b feature/your-feature-name
```
3. **Make your changes** following the code style guidelines
4. **Write tests** for new functionality
5. **Run the test suite** to ensure nothing is broken
6. **Submit a pull request**
### Code Style
- Follow Rust standard formatting: `cargo fmt`
- Address all Clippy warnings: `cargo clippy`
- Use meaningful variable and function names
- Add documentation comments for public APIs
- Keep functions focused and reasonably sized
### Before Submitting
Run the following checks locally:
```bash
# Format code
cargo fmt
# Check for common issues
cargo clippy
# Run all tests
cargo test
# Build all features
cargo build --all-features
```
## Pull Request Guidelines
### PR Title
Use a clear, descriptive title that summarizes the change:
- `Add: new embedding provider for Cohere`
- `Fix: handle empty file gracefully in chunker`
- `Improve: search performance for large codebases`
### PR Description
Include:
- **What** the change does
- **Why** the change is needed
- **How** to test the change
- Any **breaking changes** or migration steps
### Review Process
1. All PRs require at least one review
2. CI checks must pass (build, tests, clippy, fmt)
3. Address review feedback promptly
4. Squash commits before merging (if requested)
## Testing
### Running Tests
```bash
# Run all tests
cargo test
# Run a specific test
cargo test test_name
# Run tests with output
cargo test -- --nocapture
```
### Writing Tests
- Add unit tests in the same file as the code (`#[cfg(test)]` module)
- Add integration tests in the `tests/` directory
- Use the `TempProject` helper for tests that need a project directory
- Tests requiring the VSS extension should check `vss_available()` first
### Test Categories
Some tests are skipped when the DuckDB VSS extension is not available. These tests will print a message and return early:
```rust
if !common::vss_available() {
eprintln!("Skipping test: VSS extension not available");
return;
}
```
## Feature Requests and Bug Reports
### Bug Reports
When reporting a bug, please include:
- Vyctor version (`vyctor --version`)
- Operating system and version
- Steps to reproduce
- Expected vs actual behavior
- Relevant configuration (without API keys)
### Feature Requests
For feature requests:
- Describe the use case
- Explain the expected behavior
- Consider if it fits vyctor's scope
## Questions?
If you have questions about contributing, feel free to open an issue with the "question" label.
## License
By contributing to Vyctor, you agree that your contributions will be licensed under the MIT License.