|
| 1 | +# Collaborator guide |
| 2 | + |
| 3 | +This document is for approved collaborators with pull request access. Public contribution paths are documented in [`CONTRIBUTING.md`](CONTRIBUTING.md). |
| 4 | + |
| 5 | +It covers the day-to-day mechanics: how to set up the repo, how to run checks, and how to shape commits and pull requests. |
| 6 | + |
| 7 | +## Setup |
| 8 | + |
| 9 | +Requirements: |
| 10 | + |
| 11 | +- Node 22 or newer. `packages/computerd` declares `"engines": { "node": ">=22" }`. |
| 12 | +- npm. This repo uses npm workspaces, not pnpm or yarn. |
| 13 | +- Linux with FUSE if you want to run `packages/computerd` end-to-end. The rest of the workspace builds and tests on macOS as well. |
| 14 | +- Docker, optionally, for `examples/container`. |
| 15 | + |
| 16 | +Clone and install from the repo root: |
| 17 | + |
| 18 | +```bash |
| 19 | +git clone https://github.com/cloudflare/computer.git |
| 20 | +cd computer |
| 21 | +npm install |
| 22 | +``` |
| 23 | + |
| 24 | +`npm install` resolves all workspaces in one pass. Do not run `npm install` inside a single package. It creates a nested lockfile and confuses the workspace resolver. |
| 25 | + |
| 26 | +## Repository layout |
| 27 | + |
| 28 | +The repo is a small monorepo. Each package owns its own `README.md` with package-specific status and usage notes: |
| 29 | + |
| 30 | +- [`packages/dofs`](packages/dofs/) — Durable Object SQLite-backed virtual filesystem, sync protocol building blocks, and a `@platformatic/vfs` provider for Node. |
| 31 | +- [`packages/rpc`](packages/rpc/) — capnweb-based wire types and server/client helpers shared between the Durable Object and `computerd`. |
| 32 | +- [`packages/computerd`](packages/computerd/) — the `computerd` daemon: a FUSE mount plus HTTP/WebSocket RPC server that runs inside the sandbox container. |
| 33 | +- [`packages/computer`](packages/computer/) — the top-level `@cloudflare/computer` package consumed by Durable Objects. |
| 34 | +- [`packages/computer-computerd-linux-x64`](packages/computer-computerd-linux-x64/) — the prebuilt `computerd` binary for linux-x64, distributed for use in container images. |
| 35 | + |
| 36 | +[`docs/`](docs/) holds the design specification. It is forward-looking and has diverged from `main` in places. Treat it as intent, not as a description of the code today. |
| 37 | + |
| 38 | +## Code changes |
| 39 | + |
| 40 | +Touch the package that owns the behavior. Cross-package changes are fine, but group them into one logical change per commit. |
| 41 | + |
| 42 | +When you finish a task: |
| 43 | + |
| 44 | +- Update the affected package's `README.md` if its implementation status changes. |
| 45 | +- Run the checks below. |
| 46 | + |
| 47 | +## Formatting and linting |
| 48 | + |
| 49 | +Biome handles both formatting and linting. From the repo root: |
| 50 | + |
| 51 | +```bash |
| 52 | +npm run format # biome format --write . |
| 53 | +npm run check # biome lint + formatter verification |
| 54 | +``` |
| 55 | + |
| 56 | +`npm run format` is allowed to rewrite files. `npm run check` must exit zero before you push. If `check` complains, fix the underlying issue rather than silencing the rule. Disabled rules need a real justification. |
| 57 | + |
| 58 | +## Tests |
| 59 | + |
| 60 | +Run the package-level tests for whatever you touched. For the whole workspace: |
| 61 | + |
| 62 | +```bash |
| 63 | +npm test |
| 64 | +``` |
| 65 | + |
| 66 | +For a single package: |
| 67 | + |
| 68 | +```bash |
| 69 | +npm test --workspace @cloudflare/dofs |
| 70 | +``` |
| 71 | + |
| 72 | +For a single test file inside a package: |
| 73 | + |
| 74 | +```bash |
| 75 | +npm test --workspace @cloudflare/dofs -- src/path/to/file.test.ts |
| 76 | +``` |
| 77 | + |
| 78 | +`packages/computerd` includes FUSE-backed tests that only run on Linux. On other platforms they are skipped automatically. |
| 79 | + |
| 80 | +New behavior needs a test. Bug fixes need a reproduction test that failed before the fix. See [`.agents/skills/test-driven-development/SKILL.md`](.agents/skills/test-driven-development/SKILL.md) for the testing approach this repo follows. |
| 81 | + |
| 82 | +## Typecheck and build |
| 83 | + |
| 84 | +```bash |
| 85 | +npm run typecheck # tsc --noEmit across workspaces |
| 86 | +npm run build # library builds |
| 87 | +npm run build:all # libraries, bundled binaries, docker images |
| 88 | +``` |
| 89 | + |
| 90 | +`build:all` is the union of `build`, `build:bin`, and `build:docker`. Only run it if you need the binary or Docker artifacts. It is slow. |
| 91 | + |
| 92 | +## Commit messages |
| 93 | + |
| 94 | +Commit messages are read out of context, years later, by people with no memory of the change. Write them for that reader. |
| 95 | + |
| 96 | +The full guidance lives in [`.agents/skills/prose/SKILL.md`](.agents/skills/prose/SKILL.md). The short version: |
| 97 | + |
| 98 | +- **Subject line.** Imperative mood, 50 characters or fewer where possible, 72 hard maximum. No trailing period. Prefix with the package or scope: `dofs:`, `rpc:`, `computer:`, `computerd:`, `examples/think:`, `docs:`, `ci:`. Multiple scopes are joined with commas, as in `computerd, rpc: …`. |
| 99 | +- **Blank line**, then a body wrapped at 72 characters. Explain what and why, not how. The diff already shows how. |
| 100 | +- **One logical change per commit.** Do not bundle unrelated edits. |
| 101 | +- **Self-contained.** No references to chat history, agent sessions, review threads, or sibling commit SHAs. A reader on `main` in five years should understand the commit from its message alone. |
| 102 | +- **No marketing voice, no emojis, no headings or bulleted lists in the body.** Prose paragraphs. |
| 103 | +- **American English** in prose. Code identifiers keep their original spelling. |
| 104 | + |
| 105 | +`git log` is the canonical style reference. Skim a page of it before your first commit. |
| 106 | + |
| 107 | +## Pull requests |
| 108 | + |
| 109 | +A pull request tells the story behind a set of commits. Full guidance lives in [`.agents/skills/pull-requests/SKILL.md`](.agents/skills/pull-requests/SKILL.md). The shape is: |
| 110 | + |
| 111 | +1. The problem the change is solving, with a link to the issue if one exists. |
| 112 | +2. The solution and how it addresses the problem. |
| 113 | +3. How a reviewer can verify it locally: a command, a snippet, or a description of the manual test. |
| 114 | +4. The testing strategy: what is covered and what is not. |
| 115 | +5. Documentation changes, if any. |
| 116 | +6. Known follow-ups. |
| 117 | + |
| 118 | +Keep pull requests scoped to one logical change where you can. Do not include lists of changed files. The diff is right there. |
| 119 | + |
| 120 | +External pull requests are closed automatically unless they come from an owner, member, collaborator, Dependabot, Renovate, or carry the `allow-pr` label. Add `allow-pr` before reopening an external pull request that should go through review. |
| 121 | + |
| 122 | +## What not to commit |
| 123 | + |
| 124 | +- `node_modules/`, `dist/`, `artifacts/`. These are already ignored, but double-check `git status` before staging. |
| 125 | +- `.env` and `.dev.vars`. Local secrets and per-developer settings stay on your machine. |
| 126 | +- Editor or operating system scratch files. Add them to your global gitignore rather than to this repo's `.gitignore`. |
| 127 | +- Generated `worker-configuration.d.ts` files, except for the copies checked in under `examples/`. |
0 commit comments