Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
80 lines (61 loc) · 2.63 KB

CONTRIBUTING.md

File metadata and controls

80 lines (61 loc) · 2.63 KB
Raw

Contributing to CodeMind

Thank you for investing your time in contributing to CodeMind! 🧠

Quick start

git clone https://github.com/vineethwilson15/codemind.git
cd codemind
pip install -r requirements.txt
pip install pre-commit ruff
pre-commit install          # installs git hooks
cp .env.example .env
docker-compose up -d        # Neo4j + Qdrant
pytest tests/unit/          # should pass immediately (no Docker needed)

Development workflow

Branching

  • master is the protected trunk — no direct pushes
  • Branch naming: feat/<short-description>, fix/<short-description>, docs/<short-description>

Making changes

  1. Pick or open an issue before writing code — agree on the approach first
  2. Create your branch from master
  3. Write code + tests (unit tests don't need Docker)
  4. Run checks locally before pushing: 
    ruff check . && ruff format .     # lint + format
pytest tests/unit/                # unit tests
  5. Open a PR — CI and CodeRabbit AI review will run automatically

Commit messages

Follow Conventional Commits:

feat: add tree-sitter Python parser
fix: handle UTF-8 decode errors in indexer
docs: clarify dual-store invariant in CONTRIBUTING
test: add integration test for GraphClient.upsert_file

Architecture rules (enforced in code review)

Rule Where it applies
Always write Neo4j and Qdrant together core/indexer/_write_atomically()
All Neo4j writes must use MERGE, not CREATE core/graph/
CLI commands must be thin wrappers — logic lives in core/ cli/
All terminal output via rich.console.Console — never print() cli/
Unit tests must mock all external clients tests/unit/
Integration tests need @pytest.mark.integration tests/integration/

Adding a new integration

  1. Add a base class in integrations/base.py if the category is new
  2. Create integrations/<category>/<provider>.py with one class per provider
  3. Register the provider in core/config.py env vars
  4. Add unit tests mocking the provider's HTTP client
  5. Document required env vars in .env.example

Running the full test suite

# Unit only (no Docker)
pytest tests/unit/ -m unit

# Integration (requires docker-compose up -d)
pytest tests/integration/ -m integration

Code style

This project uses Ruff for both linting and formatting (configured in pyproject.toml). Run ruff check --fix . to auto-fix most issues.

Questions?

Open a Discussion — we prefer discussions over issues for questions.