Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (98 loc) · 3.91 KB

CONTRIBUTING.md

File metadata and controls

131 lines (98 loc) · 3.91 KB

Contributing to bigRAG

Thank you for your interest in contributing to bigRAG. This guide will help you get started.

Getting Started

Prerequisites

  • Python 3.12+ with uv
  • Node.js 20+ with pnpm (via corepack)
  • Docker and Docker Compose — for Postgres, Redis, Milvus

Development Setup

# Clone the repository
git clone https://github.com/bigint/bigrag.git
cd bigrag

# Start everything (backend + website + infrastructure)
./dev.sh

# Or start only specific services
./dev.sh --backend     # Docker infra + Python API
./dev.sh --website     # Docs site only
./dev.sh --infra       # Docker services only
./dev.sh --no-install  # Skip dependency installation (faster restart)

Or manually:

# Start infrastructure
docker compose up postgres redis milvus-etcd milvus -d

# Set up the Python backend
cd api
uv sync
uv run python -m bigrag.main

Project Structure

bigrag/
├── api/                   # Python/FastAPI backend
│   ├── bigrag/
│   │   ├── main.py        # App factory + lifespan
│   │   ├── deps.py        # FastAPI dependency injection
│   │   ├── config.py      # Settings
│   │   ├── db/            # SQLAlchemy engine, session, ORM models, bootstrap
│   │   ├── alembic/       # Schema migrations
│   │   ├── models/        # Pydantic request/response models
│   │   ├── services/      # Business logic (embedding, ingestion, retrieval, webhooks)
│   │   ├── routers/       # API route handlers
│   │   └── middleware/    # Auth middleware
│   ├── alembic/
│   └── pyproject.toml
├── sdks/typescript/       # TypeScript SDK (@bigrag/client)
├── website/               # Docs site (Next.js + Fumadocs)
├── docker-compose.yml     # Full stack (Postgres, Redis, Milvus, API)
├── biome.jsonc            # Biome linting config for TypeScript
├── pnpm-workspace.yaml    # pnpm workspace config
├── dev.sh                 # One-command dev setup
└── bigrag.toml            # Backend configuration

Making Changes

Branching

  • Create a feature branch from main: git checkout -b feat/my-feature
  • Use conventional commit prefixes: feat/, fix/, refactor/, docs/

Coding Standards

  • Python: Run ruff check . && ruff format . before committing
  • TypeScript: Run pnpm lint from the root (uses Biome)
  • Type hints: Use type annotations on all public functions

Verifying Changes

# Website build check
pnpm --filter @bigrag/docs build

# Lint everything
pnpm lint          # TypeScript (Biome)
cd api && uv run ruff check . && uv run ruff format --check .  # Python

Commit Messages

Use Conventional Commits:

feat: add hybrid search fusion scoring
fix: correct chunking overlap logic
refactor: simplify embedding model registry
docs: update API reference for query endpoint
test: add ingestion pipeline tests

Pull Request Process

  1. Open an issue first for significant changes to discuss the approach
  2. Create a branch from main with a descriptive name
  3. Make your changes following the coding standards above
  4. Add tests covering your changes
  5. Run the full check suite locally
  6. Push your branch and open a pull request against main
  7. Address review feedback promptly

PR Requirements

  • All CI checks must pass (lint, biome, sdk-typecheck, website-build, studio-build)
  • At least one maintainer approval
  • No merge conflicts with main

Reporting Bugs

Open an issue with:

  • bigRAG version and how you installed it (Docker, pip, source)
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant logs (set BIGRAG_LOG_LEVEL=debug for detailed output)

License

By contributing, you agree that your contributions will be licensed under the MIT License.