Skip to content

Contributing

Jump to bottom
Sanni heruwala edited this page Jun 12, 2026 · 1 revision

Contributing

The short version. For the full flow see docs/contributing.md.

The rule

 ┌──────────┐    ┌────────┐    ┌────────────┐    ┌──────────────┐    ┌────────┐
 │  Issue   ├──▶ │  Fork  ├──▶ │  Branch    ├──▶ │  PR + review ├──▶ │ Merge  │
 │  first   │    │ + clone│    │ + commits  │    │ (approval)   │    │ to main│
 └──────────┘    └────────┘    └────────────┘    └──────────────┘    └────────┘

main is a protected branch. Direct pushes blocked, every change needs ✅ green CI and ✅ approval from a maintainer listed in .github/CODEOWNERS. Drive-by PRs without a linked issue may be closed without review.

Where to file

Best on-ramps right now

Two open issues with full design docs already attached — pick one if you're looking to contribute something substantive:

Issue #3 — Cross-source joins via DuckDB ATTACH

Surface DuckDB 1.0's ATTACH in the UI so users can join Postgres + S3

  • DuckDB in one query without Trino. ~1-2 weeks of work. Design doc covers backend / frontend / edge cases / acceptance criteria.

Issue #4 — Reactive notebooks (Marimo-style)

SQL-cell dependency analysis via sqlglot + auto-rerun on upstream change. ~2-3 weeks. Design doc spells out the hard parts explicitly — please don't ship a half-baked version.

Smaller starting points

If you want something faster:

  • Athena connector — follow the existing SQLAlchemy dialect pattern in rednotebook/connectors/sqlalchemy_dialects.py.
  • Excel upload — add the DuckDB excel extension autoload + map .xlsx in _DUCKDB_READER_FOR_EXT.
  • More infographic templates — rednotebook/visualization/templates.py is one file.
  • Rename UI for uploaded files — the backend endpoint already exists (PATCH /api/files/{id}), the frontend just needs the row affordance.

Look for issues labelled good first issue or help wanted.

Development setup

git clone https://github.com/<you>/RedNotebookAI.git
cd RedNotebookAI
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
cd frontend && npm install && cd ..

Run locally:

# Terminal 1
rednotebook run                 # backend :8000

# Terminal 2
cd frontend && npm run dev      # frontend :3000

Before pushing:

pytest && ruff check .
cd frontend && npm run lint && npm run typecheck && npm run build

CI runs all of these on every PR.

What we say no to

(So you don't waste time on a PR we'll reject.)

  • Telemetry / phone-home. RedNotebook AI does not call out without the user asking it to.
  • Bypassing the read-only SQL guard. Loosening the default needs an issue discussion first.
  • Vendor-only abstractions. New connectors are great; vendor-only hooks are not.
  • Big unrelated reformatting. Keep the diff focused on what the PR actually changes.

Code of conduct

Be kind. Assume good intent. Critique code, not people. If something makes you feel unwelcome, the email in SECURITY.md reaches the maintainers privately.

Clone this wiki locally