# Contributing to Pragma Thanks for wanting to help. Please read this page before you write code — it will save you a rejected pull request. ## Table of Contents - [Contribution policy](#contribution-policy) - [Prerequisites](#prerequisites) - [First-time setup](#first-time-setup) - [Running the desktop app](#running-the-desktop-app) - [Running Pragma Go (mobile and web)](#running-pragma-go-mobile-and-web) - [Running the website and docs](#running-the-website-and-docs) - [Built-in Pragma scripts](#built-in-pragma-scripts) - [Repository tour](#repository-tour) - [Where things go](#where-things-go) - [Style guidelines](#style-guidelines) - [Testing](#testing) - [Verifying in the running app (jev)](#verifying-in-the-running-app-jev) - [Quality gates](#quality-gates) - [Release secrets](#release-secrets) - [Working with coding agents](#working-with-coding-agents) - [Commit style](#commit-style) - [Opening a pull request](#opening-a-pull-request) ## Contribution policy **We only accept small features.** Bug fixes and other small, focused changes are by far the most likely to be merged. - **Bug fixes** — very welcome. Open one for anything reproducible. - **Small features** — welcome, but open an issue first and get a maintainer to agree on the shape before you build it. - **Large features, rewrites, and sweeping refactors** — will almost certainly be declined, no matter how good the code is. Pragma's architecture is still moving, and a big unsolicited pull request is expensive to review and usually conflicts with work already in flight. - **Drive-by dependency bumps, formatting-only churn, and README rewrites** — declined unless they fix a real problem. Rules of thumb: one concern per pull request. Everything starts in the [issue tracker](https://github.com/pragma-sh/pragma/issues) — except a security vulnerability, which goes through [`SECURITY.md`](./SECURITY.md) privately, never a public issue. ## Prerequisites | Tool | Version | Notes | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Bun](https://bun.sh) | 1.4.4 or newer | Package manager and task runner. npm/yarn/pnpm are not supported. | | [Rust](https://www.rust-lang.org/tools/install) | current stable, with `clippy` and `rustfmt` | Keep it current — CI clippy runs newer lints than a stale local stable. | | [Tauri system prerequisites](https://v2.tauri.app/start/prerequisites/) | per platform | Linux additionally needs the GTK/WebKit packages plus `libpipewire-0.3-dev`, `libgbm-dev`, and `libclang-dev` (see the `rust`/`build` jobs in CI for the exact list). Windows needs nothing extra — WebView2 ships with the OS. | | [Xcode](https://developer.apple.com/xcode/) / [Android Studio](https://developer.android.com/studio) | latest | Only if you work on Pragma Go. | Platform floor for running the app: macOS, Linux, or Windows 10 version 1809 (build 17763) — ConPTY sets that floor and the server panics below it. ## First-time setup ```bash git clone https://github.com/pragma-sh/pragma.git cd pragma bun install ``` `bun install` also installs the Husky git hooks. The root `bunfig.toml` pins `linker = "hoisted"` — leave it alone, Metro and Babel in Pragma Go break under the default isolated linker. Generated code is not committed. If TypeScript complains about missing `src/generated/**` modules, run: ```bash bun run generate # regenerate shared constants for TS and Rust ``` ## Running the desktop app ```bash bun run dev # same as: bun run dev:pragma ``` That one command does more than it looks like. `tauri:dev` builds the dev-test plugin, stages the `pragma-server` sidecar, stages the Pragma Go web bundle, and then starts Tauri with `src-tauri/tauri.dev.conf.json` — a separate "Pragma Dev" identity, so a dev build and an installed release can run side by side without sharing state. Useful variations: ```bash bun run --filter pragma tauri:build # full desktop bundle for your platform bun run --filter pragma sidecar:server # restage the server sidecar only PRAGMA_SKIP_WEB=1 bun run dev # skip the Expo web export bun run jev -- run "" # Jev drives the running dev app toward a goal (see .agents/skills/jev) bun run benchmark # terminal lag benchmark (drives its own dev window) ``` You can also run the pieces directly when debugging: ```bash cargo run -p pragma-server cargo run -p pragma-gateway -- --socket /path/to/daemon.sock cargo run -p pragma-cli -- agent report --agent dev started ``` ## Running Pragma Go (mobile and web) `apps/pragma-go` is one Expo (SDK 57) source tree that builds for iOS, Android, **and**the browser. Anything a browser cannot do lives behind a `*.web.ts(x)` twin, never a `Platform.OS === "web"` branch inside a screen. ```bash bun run dev:go:ios # first run: build the dev client + boot the iOS simulator bun run dev:go:android # first run: build the dev client + boot the Android emulator bun run dev:go # Metro dev server, once the dev client is installed bun run --filter pragma-go web # Metro dev server for the browser build ``` The app is useless until it is **paired** with a running desktop: it talks to the host's local HTTP gateway through `@pragma-sh/sdk`, and without a verified connection `app/pair.tsx`replaces the whole app. Pair by QR from the desktop's pairing panel, or set `EXPO_PUBLIC_PRAGMA_GATEWAY_URL` and `EXPO_PUBLIC_PRAGMA_GATEWAY_TOKEN` for development. For the browser build the desktop serves a staged export, not a dev server: ```bash bun run --filter pragma web:stage # export Expo web into apps/pragma/src-tauri/resources/web/ ``` The gateway serves that bundle from a generated `manifest.json` by key lookup — request paths are never joined onto a filesystem path — under the `/web` base path. `/web` is deliberately unauthenticated (a `