Skip to content

Latest commit

 

History

History
167 lines (119 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

167 lines (119 loc) · 6.56 KB

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 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 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 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: 
    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

    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

# 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:

# 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

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 to connect with the community.