CONTRIBUTING.md

Contributing to GitRag

Thanks for investing time in GitRag! The project aims to stay approachable while maintaining deterministic indexing guarantees. Please follow the guidelines below when proposing changes.

Development Workflow

1. Set up the virtual environment

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

2. Run the test suite locally

   .venv/bin/python -m pytest -vv
   

   Tests stub optional dependencies (Tree-sitter, libSQL driver) where possible. When touching persistence code, run the live libSQL test by providing the CLOUDFLARE_* variables.

3. Linting is currently handled via CI formatting checks. Please keep imports clean and add targeted comments only when logic is non-obvious.

4. Commit scope: prefer focused commits per feature/fix. Each commit message should describe motivation and high-level approach (e.g., "Add CSV chunker metadata").

Making Larger Changes

• Chunker updates must include fixtures + tests that demonstrate the new behavior. For document chunking, add inputs to tests/fixtures and assertions in tests/test_chunker_documents.py.
• Persistence adapters should register via persistence_registry so they can be swapped without touching orchestration. Add tests covering registration/usage.
• CLI features should expose flags with descriptive help text and include coverage in tests/test_indexer_cli.py.

Filing Issues & Pull Requests

• Use GitHub issues to propose enhancements or report bugs. Include reproduction steps where possible.
• Draft PRs are welcome for early feedback. When ready, ensure all tests pass and the change log (README/mission docs) reflects user-facing updates.

Code of Conduct

This project follows the Contributor Covenant. By participating, you agree to uphold a welcoming, harassment-free environment.

License

By contributing, you agree that your contributions are licensed under the terms of the MIT License with GitRag attribution.