Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
66 lines (49 loc) · 2.41 KB

CONTRIBUTING.md

File metadata and controls

66 lines (49 loc) · 2.41 KB
Raw

Contributing to yaggo-brain

Thanks for your interest in improving yaggo-brain! This project is FOSS (MIT) and contributions of all sizes are welcome. Español: CONTRIBUTING.es.md.

Ways to contribute

  • Report bugs and rough edges via Issues.
  • Propose features or design changes (open an issue first for anything large).
  • Improve documentation (including translations).
  • Send pull requests for bug fixes and features.

Development setup

# Prerequisites: Node.js >= 20, pnpm (repo pins pnpm@11.9.0), Docker, Git
pnpm install
cp .env.example .env
pnpm db:up          # Postgres (AGE + pgvector), Valkey, Ollama, LiteLLM, Langfuse, workers
pnpm db:migrate
pnpm dev            # web :3000, api :3333, worker :37700

Optional local models:

docker exec yaggo-ollama ollama pull nomic-embed-text
docker exec yaggo-ollama ollama pull qwen2.5:3b
docker exec yaggo-ollama ollama pull qwen2.5-coder:7b

Before you open a PR

  • pnpm typecheck is green.
  • pnpm test passes.
  • pnpm lint is clean for the files you touched.
  • New behavior has a test and/or an eval case.
  • Docs updated if you changed public behavior or config.

Engineering principles

  • Surgical changes. Keep diffs focused; avoid unrelated refactors.
  • No hallucinated APIs/versions. Verify library usage before writing it.
  • Minimalism. Prefer the simplest solution that works; avoid speculative abstractions.
  • License hygiene. Do not add AGPL/GPL dependencies to the core. Permissive licenses (MIT / Apache-2.0 / BSD / PostgreSQL) only.
  • Local-first & private. Don't add code that exfiltrates user code or data by default.
  • Code and comments in English. Comments should explain intent/trade-offs, not narrate.

Commit & PR conventions

  • Conventional-style prefixes are appreciated: feat:, fix:, docs:, refactor:, test:, chore:.
  • Describe the "why", not just the "what".
  • Reference related issues (Closes #123).
  • One logical change per PR when possible.

Project layout

apps/* (web, api, worker, mcp-server, mcp-proxy, observatory, sandbox-runner, cli), packages/* (shared libraries), infra/* (Docker Compose + Python workers), templates/* (harness templates the product ships), evals/*, scripts/*.

Code of Conduct

By participating you agree to the Code of Conduct.