Home Getting Started Contributing

Contributing

Last updated on May 16, 2026

Contributing

Orange Way is Apache 2.0. PRs welcome. This page covers the repo conventions, branch model, and what to know before opening a PR.

Branch model

Two branches, two URLs. No main.

dev   ← Lovable + agents + PRs land here; auto-deploys to dev.orangeway.app
prod  ← merged from dev when ready; auto-deploys to orangeway.app (live)

Full breakdown: Branch flow — dev and prod.

Promotion command (run after dev verification):

git fetch origin
git checkout prod
git merge --ff-only origin/dev
git push origin prod

PR conventions

  • Open against dev (the GitHub default branch — should auto-select).
  • Commit format: type(scope): subject. Types we use: feat, fix, chore, docs, ci, copy, refactor, test.
  • Maintainer squash-merges by default; single-commit PRs are easier to review.
  • CI must pass (bun run build, type check, the M-suite Playwright tests for any UI change).

Setting up locally

gh repo clone MorningRevolution/orange-way
cd orange-way
bun install
bun run dev    # localhost:8080

For backend work (edge functions, migrations), you'll need a Supabase project. Either:

  • Use the hosted dev project (ask a maintainer for read access).
  • Run Supabase locally via supabase start.

Copy .env.example to .env and fill in:

VITE_SUPABASE_URL=https://<dev-ref>.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY=<anon-key>
VITE_SUPABASE_PROJECT_ID=<dev-ref>
VITE_OR_SUPABASE_URL=https://api.orangerails.com
VITE_OR_PLATFORM_ID=<orangeway-platform-id-on-or-dev>

Repo layout

src/
  routes/             TanStack Router file-based routes
  components/         UI components
  context/            React contexts (VaultContext, AuthContext, etc.)
  hooks/              React hooks
  lib/                Pure utilities (crypto, vault, HSK, OSK, etc.)
  pages/              Page-level components
  integrations/       Supabase client + types

supabase/
  functions/          Edge functions (signup, household-invite, hsk-mint, etc.)
  migrations/         Versioned SQL (idempotent guards required)

scripts/              Build helpers, test runners, CCXT manifest generators
tests/                Playwright + Vitest

Code style

  • TypeScript everywhere. Avoid any.
  • Plain English in user-facing copy. No "rotate", "encrypt", "decrypt" — say "lock", "open the box", "scrambled bytes" instead.
  • No em-dashes in user-facing copy. Commas, periods, parentheses.
  • No compound-word hyphens in user-facing copy ("customer facing", not "customer-facing").
  • Tests for any new edge function (Vitest). UI changes that hit a flow get a Playwright test in the M-suite.

Privacy is non-negotiable

PRs that break zero-knowledge will be rejected. The architectural rule is server stores ciphertext only for transactions, balances, categories, goals, household relationships. Vault password, HSK, OSK never leave the browser.

If you're adding a new feature that touches user data, the default question is: can the server see this? If yes, you need a different design. Ask in a PR draft before going deep.

What we don't accept yet

  • PRs that move plaintext data server-side.
  • PRs that add a hard dependency on a non-free service without a self-host fallback.
  • PRs that change the public API in breaking ways without a deprecation cycle.
  • Massive PRs (>500 lines net) without a prior design discussion — open an issue or a draft first.

Discussion

License

Apache 2.0. See LICENSE in repo root.