Skip to content

contributing.md

Latest commit

 

History

History
66 lines (53 loc) · 2.69 KB

contributing.md

File metadata and controls

66 lines (53 loc) · 2.69 KB
Raw

Contributing to Atlas

Ten commandments

  1. Tenant isolation is not optional. Every query against a tenant-scoped table runs inside session_for_org(...). RLS is forced on every such table. If you can't see how to do something without bypassing RLS, stop and ask.
  2. Idempotency is mandatory for every webhook handler, every Inngest function, every external mutation.
  3. Every external call has a timeout, a retry, and a circuit breaker.
  4. All LLM calls go through apps/api/atlas/llm/. No direct SDK use anywhere else.
  5. Citations are sacred. Refuse rather than hallucinate.
  6. No customer data in logs. Log IDs, hashes, lengths, timings — never message bodies. The structured logger hashes known PII fields automatically.
  7. Migrations are forward-only. Use expand-migrate-contract across two releases for destructive changes.
  8. No secrets in code or commits. Secrets live in Railway/Vercel env stores; per-row customer secrets are envelope-encrypted via KMS.
  9. Type-safe end to end. mypy --strict in Python, tsc --strict in TS.
  10. Tests are not optional. Every PR includes them.

DO-NOT list (high-velocity reminders)

  • Don't call OpenAI/Anthropic from route handlers — go through atlas/llm/.
  • Don't SELECT * in production queries.
  • Don't trust webhook payloads without signature verification.
  • Don't embed user input directly in LLM system prompts — use <context> / <question> delimiters.
  • Don't use floats for money — integer USD micros only.
  • Don't introduce a new dependency without a written justification in the PR.

PR process

  • Target ≤ 400 LOC diff.
  • Conventional Commits (feat:, fix:, chore:, docs:, etc.).
  • Fill out the PR template (what / why / how tested / risks / rollout).
  • At least one reviewer. Security-sensitive paths require two (see CODEOWNERS).
  • Eval run is required for changes under apps/api/atlas/query/ or apps/api/atlas/ingestion/.

Coding standards (cheat sheet)

Python

  • Python 3.12, async-first, Pydantic v2, SQLAlchemy 2.0 async.
  • Lint + format: uv run ruff check . && uv run ruff format .
  • Types: uv run mypy --strict atlas
  • Tests: uv run pytest -q

TypeScript

  • TS 5.4+, tsc --strict, ESLint + Prettier.
  • React functional components only.
  • TanStack Query for server state; Zustand for UI state.
  • No any, no // @ts-ignore without inline justification.

Reviewing

  • Look at the data model first. Bad migrations are forever.
  • Read every SQL query against tenant tables. Confirm it runs through session_for_org.
  • Run the change locally if you can't reason about it from the diff.
  • Be kind. Critique the code, not the author.