Skip to main content

Contributing

Contributions are welcome. The full CONTRIBUTING.md has detailed instructions.

Quick Start​

The full Docker Compose stack is the fastest route to a working dev environment, and the Setup Guide covers it. For development on the host:

# Bring up just the supporting services
docker compose up -d postgres redis

# Backend
cd backend
python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r requirements-test.txt
alembic upgrade head
uvicorn app.main:app --reload

# Frontend
cd frontend && npm install && npm run dev

# Tests
cd backend && pytest
cd frontend && npm test

Pre-push hook​

When enabled (git config core.hooksPath .githooks), .githooks/pre-push runs checks for whichever side changed. For backend/ changes it runs pytest (-x -q), which includes the API-doc guard via test_api_doc.py. For frontend/ changes it runs the type-check (tsc --noEmit), lint (npm run lint -- --max-warnings 0), and tests (vitest). It also blocks a push that changes chrome-extension/ code without bumping the version in chrome-extension/manifest.json. The response-model guard (scripts/check_response_models.py) is a separate CI or manual check that the hook does not run. The hook activates backend/.venv when it exists, so any new test dependency added to requirements-test.txt must also be installed in that venv:

cd backend && source .venv/bin/activate && pip install -r requirements-test.txt

Never push with --no-verify unless explicitly asked to.

Pull Request Process​

  1. Fork the repo and create a branch from main
  2. Make your changes with tests
  3. Ensure pytest and npm test both pass
  4. Run the API-doc guard if you touched any FastAPI route: PYTHONPATH=. python3 scripts/check_api_doc.py
  5. Submit a PR with a clear description

Code Style​

  • Python: snake_case, type hints, async where appropriate
  • TypeScript: camelCase for variables/functions, PascalCase for components

See CLAUDE.md for the full conventions guide.