# Contributing to ChunkHound
Welcome to ChunkHound! We're excited you're interested in contributing to a **100% AI-generated codebase**.
## Our Mission: No Compromise on Quality
ChunkHound maintains a **100% AI-generated codebase** without compromising on production quality. Why? Because it's the only way to push forward AI-assisted development technology and truly eat our own dog food. Every line of code, documentation, and feature has been generated by AI agents working with human guidance.
Read our [origin story](https://chunkhound.github.io/origin-story/) to see how ChunkHound bootstrapped itself from an empty repository to a functional POC in a single day.
## Getting Started
### 1. Install and Set Up ChunkHound
Follow the [Tutorial](https://chunkhound.github.io/tutorial/) to:
- Install ChunkHound with `uv`
- Configure your embedding provider (OpenAI, VoyageAI, or Ollama)
- Index ChunkHound's own codebase
- Set up MCP integration with your AI agent
### 2. Use Code Research
Use ChunkHound's built-in [Code Research](https://chunkhound.github.io/code-research) tool to analyze the codebase architecture before making any changes. This tool helps your agent understand existing patterns and identify the minimal changes needed.
## Development Workflow
### Before Writing Any Code
**Always use Code Research first:**
```
Research the codebase. Consider the surrounding code style, architecture, and module responsibilities.
Think of the minimal required changes that reuse as much as possible.
```
This ensures your agent:
- Understands existing patterns and conventions
- Reuses existing mechanisms instead of duplicating code
- Follows the established architecture
- Makes minimal, targeted changes
### Quality Standards
1. **Match existing patterns** - Study how similar features are implemented
2. **Minimize changes** - Prefer editing existing files over creating new ones
3. **Reuse mechanisms** - Don't reinvent existing functionality
4. **Test thoroughly** - Always run smoke tests before commits:
```bash
uv run pytest tests/test_smoke.py -v
```
5. **AI-generated only** - All code must be generated by AI agents
### Testing Philosophy
ChunkHound's testing approach is designed for a 100% AI-generated codebase:
1. **Smoke tests are mandatory** - Always run before commits (`uv run pytest tests/test_smoke.py -v`)
- Primary safety guardrail against AI-introduced breaking changes
- Catch import-time crashes and type annotation bugs in ~10 seconds
2. **Real components over mocks** - Exercise actual functionality whenever possible
- Use real file systems, temporary directories, actual components
- Only mock external services when absolutely necessary
- **Tests must pass 100% on all platforms** (Windows, macOS, Linux)
3. **Fast feedback over coverage** - Prioritize immediate failure detection
- Better fewer reliable tests than many flaky ones
- Clear error messages to guide AI corrections
4. **Tests as AI guardrails** - Define expected behavior to guide AI agents
- Write failing tests first to specify requirements
- Tests serve as safety nets during AI-driven development
## Dependency Management
ChunkHound uses a multi-layered dependency management strategy to ensure both library compatibility and reproducible deployments:
### Files and Their Purpose
1. **`pyproject.toml`** - Library dependencies with flexible constraints
```toml
dependencies = [
"duckdb>=1.4.0", # Allows patch updates for compatibility
"openai>=1.0.0", # Flexible for downstream users
]
```
- Uses `>=` constraints for published library
- Prevents version conflicts for users
- Modified only when adding/removing dependencies
2. **`uv.lock`** - Exact development environment
- Contains precise versions of all dependencies
- Generated by `uv lock` and `uv sync`
- Committed to ensure reproducible development
- Updated when dependencies change
3. **`requirements-lock.txt`** - Production deployment versions
- Contains exact versions for production installs
- Generated by `uv pip compile pyproject.toml --all-extras -o requirements-lock.txt`
- Updated automatically during release preparation
- Ensures reproducible production deployments
### Development Workflow
```bash
# Add a new dependency
uv add "new-package>=1.0.0"
# Update all dependencies
uv lock --upgrade
# Install exact development environment
uv sync
# Generate production lock file (done automatically by prepare_release.sh)
uv pip compile pyproject.toml --all-extras -o requirements-lock.txt
```
### Release Process
ChunkHound uses **dynamic versioning** via hatch-vcs - versions are automatically derived from git tags during builds.
#### Creating a New Version
Use the `update_version.py` script to create PEP 440 compliant version tags:
```bash
# Release versions
uv run scripts/update_version.py 4.1.0 # Standard release
uv run scripts/update_version.py --bump minor # Bump to next minor
# Pre-release versions (for beta channel)
uv run scripts/update_version.py 4.1.0b1 # Beta release
uv run scripts/update_version.py 4.1.0rc1 # Release candidate
uv run scripts/update_version.py --bump minor b1 # Bump to next minor beta
```
#### Publishing Workflow
1. **Create version tag**: Use `update_version.py` (see above)
2. **Run smoke tests**: `uv run pytest tests/test_smoke.py -v` (MANDATORY)
3. **Prepare release**: `./scripts/prepare_release.sh`
- Regenerates `requirements-lock.txt` with exact versions
- Ensures all lock files are synchronized
- Creates reproducible release artifacts
4. **Test locally**: `pip install dist/chunkhound-X.Y.Z-py3-none-any.whl`
5. **Push tag**: `git push origin vX.Y.Z`
6. **Publish**: `uv publish` (requires PYPI_TOKEN)
This ensures that users can install ChunkHound with either:
- **Library install**: `pip install chunkhound` (flexible dependencies)
- **Production install**: `pip install -r requirements-lock.txt` (exact versions)
## Community
- **Discord:** [https://discord.gg/BAepHEXXnX](https://discord.gg/BAepHEXXnX)
- **GitHub Discussions:** [https://github.com/chunkhound/chunkhound/discussions](https://github.com/chunkhound/chunkhound/discussions)
- **Documentation:** [https://chunkhound.github.io](https://chunkhound.github.io)
- **Issues:** Use GitHub Issues for bug reports and feature requests
## License
By contributing to this project, you agree that your contributions will be licensed under the same MIT License as ChunkHound.
---
Ready to contribute? Start by indexing ChunkHound with itself, configure Code Research, and join our [Discord](https://discord.gg/BAepHEXXnX) to connect with the community.
