| 1 | # Contributing to g1t |
| 2 | |
| 3 | g1t is built the way it asks others to build: issues and pull requests on |
| 4 | [g1t.sh/flagon-io/g1t](https://g1t.sh/flagon-io/g1t), required checks that prove |
| 5 | a change works, and a merge queue that keeps `main` passing. |
| 6 | |
| 7 | ## A change ships with its docs |
| 8 | |
| 9 | Documentation is part of the product, held to the same bar as the code. |
| 10 | A pull request that changes what someone can do, see or call changes the |
| 11 | docs in the same pull request: |
| 12 | |
| 13 | | If you change | Update | |
| 14 | | --- | --- | |
| 15 | | Something a person does on g1t.sh | The guide for it in `apps/docs/src/content/docs/guides/` | |
| 16 | | An API route, a field, or an MCP tool | `apps/api/src/operations.rs` descriptions (they feed the OpenAPI document and the API reference), the example and notes for it in `apps/api/src/reference.json`, `reference/mcp.md`, and any guide that shows the call. Then refresh the docs' copy of the OpenAPI document with `G1T_WRITE_OPENAPI=1 cargo test -p g1t-api openapi`; `cargo test` fails until you do. | |
| 17 | | How agents behave | `guides/working-with-g1t.md`, and `apps/web/public/llms.txt` | |
| 18 | | Settings, limits or prices | The page that names them, and the table it is in | |
| 19 | | A new feature | A section in the guide that owns it, linked from the docs home if it is a new task | |
| 20 | | How g1t is put together: a service, a binding, a store, an event route, the path of a request | Its page in the docs' Architecture section (`apps/docs/src/content/docs/architecture/`), and its diagram in `apps/docs/src/diagrams/architecture.ts`. [How g1t ships](https://docs.g1t.sh/architecture/shipping/#keeping-this-section-true) says which page covers what. | |
| 21 | |
| 22 | The style, in short: plain sentences, second person, no marketing words, |
| 23 | sentence-case headings, a numbered list for steps, a table for options, and |
| 24 | every API mention with its exact route or tool name. Examples are copyable |
| 25 | and real. Nothing is documented that the code does not do. |
| 26 | |
| 27 | Check the docs build before you push: |
| 28 | |
| 29 | ```sh |
| 30 | cd apps/docs && npm run build |
| 31 | ``` |
| 32 | |
| 33 | ## Icons |
| 34 | |
| 35 | - **Interface icons come from [Lucide](https://lucide.dev/icons).** In the |
| 36 | apps, import them from `lucide-react`. In the docs, use `@lucide/astro`: |
| 37 | import an icon component, or give `apps/docs/src/components/Card.astro` |
| 38 | and `Aside.astro` a Lucide name such as `icon="git-branch"`. Starlight's |
| 39 | own `<Card>`, `<LinkCard>` and `<Aside>` draw Starlight's icon set, so the |
| 40 | docs import the wrappers in `apps/docs/src/components/` instead. |
| 41 | - **Brand marks come from [Simple Icons](https://simpleicons.org)** |
| 42 | (`simple-icons`), and follow each brand's own usage guidelines. Add the |
| 43 | dependency with the first one you show. |
| 44 | - **The g1t logo and illustrations are our own artwork**, in |
| 45 | `apps/web/app/components/logo.tsx` and `art.tsx`. |
| 46 | - Never hand-copy an icon's SVG paths into a file. If Lucide lacks the |
| 47 | icon you need, pick the closest one that it has. |
| 48 | |
| 49 | ## Interface components |
| 50 | |
| 51 | - **Build the site from the components in `apps/web/app/components/ui`**, |
| 52 | which are [shadcn/ui](https://ui.shadcn.com) components themed with |
| 53 | g1t's tokens: buttons, cards, badges, tables, tabs, separators, |
| 54 | breadcrumbs, menus, dialogs, sheets, tooltips, form controls. |
| 55 | - **If shadcn has a component you need and `ui` doesn't, add it there** |
| 56 | first, themed with the tokens, then use it. Don't rebuild it inline. |
| 57 | - **Change how something looks through the component's variants**, not |
| 58 | with a one-off class string at the call site. A long `className` on a |
| 59 | `div` that draws a card, a pill or a button is a component that should |
| 60 | exist. |
| 61 | - Hover hints use the `Tooltip` component, never `title=`. Native |
| 62 | `<select>`, file inputs, checkboxes and radios use their `ui` |
| 63 | components. |
| 64 | - **Every avatar is `Avatar`** (`ui/avatar.tsx`), and every agent's is |
| 65 | `Avatar` with `agent` set, or `AgentAvatar` (`components/agent-avatar.tsx`), |
| 66 | which wraps it. That draws the agent's bot face (`AgentFace`, |
| 67 | `components/agent-face.tsx`) from its `look` or its `avatar_seed`, puts |
| 68 | the agent marker in its corner and names it "…, agent" to a screen |
| 69 | reader. Never hand-draw an agent's face, a sparkle, a letter on a tile or |
| 70 | the marker at a call site: a place that shows an agent differently is a |
| 71 | bug. |
| 72 | - Look at every page you change, in light and dark, on a desktop and a |
| 73 | phone, before calling it done. |
| 74 | |
| 75 | ## Before you push |
| 76 | |
| 77 | - `cargo test` in the crate or service you changed. |
| 78 | - `npx tsc -b --force` in `apps/web` (the incremental build misses changes |
| 79 | in `packages/contracts`). |
| 80 | - Look at what you changed in a browser. Screenshots catch what type |
| 81 | checks do not. |
| 82 | |
| 83 | ## Checking g1t against GitHub |
| 84 | |
| 85 | g1t runs GitHub Actions workflows as GitHub does. The Conformance |
| 86 | workflow is how that is checked: `.g1t/workflows/conformance.yml` and |
| 87 | `.github/workflows/conformance.yml` are the same file (a test in |
| 88 | `crates/actions` fails when they differ), and each run's |
| 89 | `conformance-report` artifact records what its jobs saw: which `GITHUB_*` |
| 90 | and `RUNNER_*` variables were set and of what kind, every key of the |
| 91 | contexts and the event and its type, how the workspace is laid out, and |
| 92 | the values of outputs, files, caches, artifacts and expressions that |
| 93 | should be the same everywhere. It reads no secrets and runs only by hand. |
| 94 | |
| 95 | 1. Run it on both, at the same commit: **Actions → Conformance → Run |
| 96 | workflow** on GitHub and on g1t.sh. |
| 97 | 2. Download each run's `conformance-report` artifact, and name the two |
| 98 | files `github.json` and `g1t.json`. |
| 99 | 3. Compare them: |
| 100 | |
| 101 | ```sh |
| 102 | node scripts/conformance-diff.mjs github.json g1t.json |
| 103 | ``` |
| 104 | |
| 105 | It lists what GitHub has that g1t lacks or has otherwise, then what only |
| 106 | g1t has, and exits 1 while there are differences. A difference is a bug in |
| 107 | g1t, or belongs in [What g1t can't do yet](https://docs.g1t.sh/about/limitations/). |
| 108 | Add a step and a `CHECK_` value to the workflow for anything new g1t |
| 109 | should match. |
| 110 | |
| 111 | ## Deploying |
| 112 | |
| 113 | Pushes to `main` deploy themselves: `.g1t/workflows/deploy.yml` runs |
| 114 | `scripts/deploy.mjs`, which deploys only the parts that changed, migrations |
| 115 | first. Every deployable part is listed in `deploy/stack.jsonc`; a new service |
| 116 | or app goes there, in the table on |
| 117 | [How a self-hosted g1t runs](https://docs.g1t.sh/guides/self-hosting-architecture/#each-part), |
| 118 | and in the one on [Services and contracts](https://docs.g1t.sh/architecture/services/#every-unit) |
| 119 | (`npm run test:deploy` says what is missing). |
| 120 | [Deploy g1t to Cloudflare](https://docs.g1t.sh/guides/deploy-to-cloudflare/) |
| 121 | covers the tool, the workflow, rollbacks, adding a unit and first-time |
| 122 | setup. |
| 123 | |
| 124 | - **Migrations run before the code**, so the old code reads the new schema |
| 125 | for a minute or more. Add tables and columns; change what rows mean in |
| 126 | two deploys (code that reads both forms first); never drop what live code |
| 127 | still reads. |
| 128 | - **The self-hosted runner** is released, not deployed: bump `version` in |
| 129 | `crates/runner/Cargo.toml`, merge, and push a `runner-v<version>` tag. |
| 130 | `.g1t/workflows/runner-release.yml` builds, signs and publishes it, and |
| 131 | runners update themselves to it. `scripts/runner-release.mjs` does the |
| 132 | same by hand. |
| 133 | - **The g1t CLI** is released the same way: bump `version` in |
| 134 | `crates/g1t/Cargo.toml`, merge, and push a `cli-v<version>` tag. |
| 135 | `.g1t/workflows/cli-release.yml` builds it for every platform, signs |
| 136 | the release with the runner's release key and publishes it to |
| 137 | g1t.sh/downloads/cli/, where g1t.sh/install and g1t.sh/install.ps1 |
| 138 | find it. `scripts/cli-release.mjs` does the same by hand. The command |
| 139 | reference in the docs is generated from the CLI |
| 140 | (`G1T_WRITE_DOCS=1 cargo test -p g1t cli_reference`), and its table of |
| 141 | API operations from the OpenAPI document |
| 142 | (`G1T_WRITE_OPS=1 cargo test -p g1t ops_table`); tests fail when either |
| 143 | falls behind. The guide is [The g1t CLI](https://docs.g1t.sh/guides/cli/). |
| 144 | - **The desktop app** is released the same way: bump `version` in |
| 145 | `apps/desktop/src-tauri/Cargo.toml`, merge, and push a |
| 146 | `desktop-v<version>` tag. `.g1t/workflows/desktop-release.yml` builds |
| 147 | the installers (Linux on g1t's machines; Windows and macOS on machines |
| 148 | registered for them, or Windows cross-built on Linux once its download |
| 149 | hosts are allowed, each switched on by a repository variable the |
| 150 | workflow's header names; a platform with no machine is left out of that |
| 151 | release), signs the updater's files and publishes them, and installed |
| 152 | apps update themselves. `scripts/desktop-release.mjs` does the |
| 153 | same by hand. The app loads the live site, so a change to the site needs |
| 154 | no release; only a change under `apps/desktop` does. The guide is |
| 155 | [The desktop app](https://docs.g1t.sh/guides/desktop/). |
| 156 | - **The phone app** for Android is released on g1t.sh/download while it |
| 157 | is not in Google Play (that waits on Flagon's D-U-N-S number): bump |
| 158 | `version` in `apps/mobile/app.config.ts` when its native side changes, |
| 159 | merge, and push a `mobile-v<version>` tag. |
| 160 | `.g1t/workflows/mobile-release.yml` has EAS build the APK and publishes |
| 161 | it; `scripts/mobile-release.mjs` does the same by hand. A change to the |
| 162 | app's code alone needs no release: `eas update --channel preview` in |
| 163 | `apps/mobile` reaches installed copies. Its server half (chat scopes, |
| 164 | `/-/notify`, notify's phone push) deploys with the site and services. |
| 165 | The guide is [The phone app](https://docs.g1t.sh/guides/mobile/). |
| 166 | |
| 167 | ## How g1t's own CI caches |
| 168 | |
| 169 | g1t's workflows cache with `actions/cache` against g1t's own cache |
| 170 | ([the Actions guide](https://docs.g1t.sh/guides/actions/#the-cache) has its |
| 171 | rules). Three of them shape everything here: a run restores from its own |
| 172 | ref, its pull request's base, then `main`, so a release tag never reads |
| 173 | another tag's entries; a key is written once; and a repository holds |
| 174 | 10 GiB, past which the entries restored longest ago go. So: |
| 175 | |
| 176 | - **`main` saves; pull requests and tags restore.** CI's Rust and desktop |
| 177 | jobs keep their caches on each push to `main`, and the Caches workflow |
| 178 | (`.g1t/workflows/caches.yml`) builds and saves what only releases use, |
| 179 | when its key is missing. Release workflows only restore. |
| 180 | - **Rust caches are keyed by the toolchain and the dependencies**, from |
| 181 | `node scripts/deploy/ci-cache.mjs keys`: `rustc -V`, and a hash of the |
| 182 | packages `Cargo.lock` takes from crates.io and git. A release bumping a |
| 183 | workspace crate's version changes neither. A restore key never crosses |
| 184 | toolchains. |
| 185 | - **A Cargo target restored from an older entry is pruned before it is |
| 186 | saved** (`ci-cache.mjs prune`), to what this build used. |
| 187 | - **A partial install never saves a whole-install key.** npm's downloads |
| 188 | and the crates are saved only by jobs that fetch all of them. |
| 189 | - **One set of paths per entry.** An entry's version is the hash of its |
| 190 | paths, so every step that names it, in every workflow, names the same |
| 191 | ones. `crates/actions/tests/repository_workflows.rs` holds all of this. |
| 192 | |
| 193 | | Entry | Key | Saved by | Restored by | |
| 194 | | --- | --- | --- | --- | |
| 195 | | npm's downloads | `npm-full-<os>-<package-lock.json>` | Caches (`npm`) | every npm install | |
| 196 | | Crates and their index | `cargo-crates-<os>-<deps>` | CI Rust (`cargo fetch` of the whole lockfile) | Deploy, the runner release | |
| 197 | | The test build | `cargo-test-<os>-<rust>-<deps>` | CI Rust | CI Rust on pull requests | |
| 198 | | Workers' builds | `cargo-workers-<os>-<rust>-<group>-<deps>` | Deploy | Deploy | |
| 199 | | The runner's image build | `runner-musl-<os>-<rust>-<deps>` | Deploy | Deploy | |
| 200 | | worker-build and its tools | `worker-build-…`, `worker-build-tools-…` | Deploy | Deploy | |
| 201 | | Compiled crates | sccache's, one per crate | every Rust job | every Rust job | |
| 202 | | The desktop app's check | `desktop-check-<os>-<rust>-<desktop deps>` | CI desktop | CI desktop on pull requests | |
| 203 | | apt for Tauri | `apt-tauri-<os>-<scripts/apt-install.sh>` | CI desktop | the desktop release | |
| 204 | | The runner release | `runner-release-<os>-<target>-<rust>-<deps>`, zig | Caches (`runner`) | the runner release | |
| 205 | | The desktop release | `desktop-release-linux-…`, `desktop-release-windows-…`, `xwin-…`, `apt-tauri-windows-…` | Caches (`desktop-linux`, `desktop-windows`) | the desktop release | |
| 206 | |
| 207 | To see whether a change helped, read a run's cache steps: `Cache restored |
| 208 | from key` names the entry (the key itself is a hit; another is a start), |
| 209 | `Cache Size` and the step's time say what it cost, and the post step says |
| 210 | whether it saved. `sccache's hits and misses` is on each Rust job's summary. |
| 211 | |
| 212 | ## Speed |
| 213 | |
| 214 | Pages are a few rounds of service calls, and each round costs a trip to |
| 215 | the databases, so start calls together and add no rounds. |
| 216 | |
| 217 | - Every page answers with `Server-Timing`: each loader, each service's |
| 218 | calls and their database time. Look at it in DevTools when a page feels |
| 219 | slow. |
| 220 | - `scripts/perf/measure.ps1` times pages from your machine (`-BrowserUA` |
| 221 | for signed-out pages as a browser sees them). A page that only reads |
| 222 | must not set the `g1t_d1` cookie: a new read-only service method goes in |
| 223 | `READS` in `apps/web/app/lib/perf.ts`. |
| 224 | - Targets from the US: signed-out pages under 200 ms to first byte, |
| 225 | signed-in pages under 400 ms, streamed panels within a second. |
| 226 | - Workers run without Smart Placement; `scripts/perf/placement-probe.mjs` |
| 227 | measures a placement before you pin one. |
| 228 | - A TypeScript service reports its database time too (`db;dur`, from |
| 229 | `openD1` in `@g1t/contracts`): the round trips a method makes are what |
| 230 | it costs, so start them together (`Promise.all`), keep what never |
| 231 | changes across requests in the isolate (the artifacts service keeps a |
| 232 | workspace's slug for 30 s and whether its General space exists), and |
| 233 | don't wake a Durable Object for a read D1 can answer. |
| 234 | - Nothing live gates a page. A page carries what it shows (a doc's text |
| 235 | and its saved document), opens its sockets as it hydrates rather than |
| 236 | from inside the code they feed, keeps what is typed until they answer, |
| 237 | and says so with a dot, never a spinner. A page opened with an access |
| 238 | token gets its socket tickets with the page (the root loader mints the |
| 239 | feed's, an artifact's loader its room's) rather than asking for each. |
| 240 | - Code that only the browser runs (the doc editor) is still fetched with |
| 241 | the page: `vite.config.ts` notes the chunk and what it imports for the |
| 242 | route's `links`, and a link to such a page warms the chunk on hover. |
| 243 | Modules several routes share are grouped by who shares them |
| 244 | (`codeSplitting.groups`), so a page fetches tens of files, not a |
| 245 | hundred and more. Before this, opening a doc fetched 124 files |
| 246 | (1,049 KB) in three waves and the editor appeared at 2.8–3.3 s; a doc |
| 247 | now fetches 71 files (1,026 KB) in one wave, and against the deployed |
| 248 | services the editor appears at 2.1 s, of which the room's answer is |
| 249 | 0.65 s and the editor's own start 0.4 s. With the saved document in the |
| 250 | page, measured on g1t.sh signed in (2026-10-10, warm, 1440×900), the |
| 251 | editor appears at 1.5 s: first byte 0.53 s, scripts by 0.75 s, the |
| 252 | editor's own start the rest. A doc without a saved document (one last |
| 253 | saved before documents were kept) waited for its room's first message |
| 254 | instead, 0.9 s after the socket opened, and appeared at 2.0–2.5 s; the |
| 255 | page now asks the room once and keeps the answer, so only its first |
| 256 | open pays. Still to cut: the live socket's four service calls before |
| 257 | the room answers, the page and sidebar's 27 database round trips in two |
| 258 | calls, the root loader's billing and identity calls (0.7–1.3 s and |
| 259 | 0.45 s inside), and the 3.4 MB of script a doc page decodes. |
| 260 | |
| 261 | ## Rate limits |
| 262 | |
| 263 | `RATE_LIMITS` in `packages/contracts/src/rate-limits.ts` is the table of |
| 264 | record, and the [rate limits page](https://docs.g1t.sh/reference/rate-limits/) |
| 265 | is the public one: change both, and the binding in the Worker's |
| 266 | `wrangler.jsonc`, together (`front-door-limits.test.ts` fails when they |
| 267 | disagree). Limits fail open, keys hash anything secret, and each Worker |
| 268 | takes its namespace ids from its own block of a hundred (41xx packages, |
| 269 | 42xx web, 43xx repos, 44xx api, 45xx og, 46xx status). |
| 270 | |
| 271 | ## Operating g1t.sh |
| 272 | |
| 273 | For Flagon staff. |
| 274 | |
| 275 | - **Incidents** are declared, updated and resolved in sudo, under |
| 276 | **Platform → Incidents**, and appear on status.g1t.sh within 30 seconds. |
| 277 | Declare as soon as people are affected, and pick the higher severity |
| 278 | when unsure. SEV1 (down for most people, or data at risk) gets an update |
| 279 | at least every 30 minutes and SEV2 (a core part broken for many) at least |
| 280 | hourly; both email subscribers and need a blameless postmortem within |
| 281 | five working days. |
| 282 | - **An Artifacts outage:** `scripts/ops/gitstore-namespaces.mjs` shows a |
| 283 | failing namespace. After 15 minutes, serve it read-only from the fallback |
| 284 | git store (`scripts/ops/restore-to-gitstore.mjs restore`, then the repos |
| 285 | Worker's secret `GIT_FALLBACK_NAMESPACES`) and open an incident. To |
| 286 | switch back, `reconcile` anything the fallback took, then delete the |
| 287 | secret. The script's header has every step. |
| 288 | - **Costs and margin**, model prices, credits and the platform pause are |
| 289 | in sudo, under **Costs & margin**. The code is in `services/billing/src` |
| 290 | (`costs.rs`, `margin.rs`, `pricing.rs`, `budget.rs`, `platform.rs`). |