Contributing

The rules a change is held to

What is open and what is settled is status and roadmap, the ones deliberately not moving are accepted limits, testing your backend is the split these rules assume, and getting help is where to ask first.

One Zod object is a table’s whole definition. The app shape on one side, the SQLite row on the other, every conversion through a codec, and every field described.

Validate at every boundary — including the ones people forget are boundaries. A model’s response is one: a text model will always produce a plausible-sounding label, and an invented one silently poisons every filter downstream.

Guards before validators. A validator ahead of a guard turns a 401 into a 400 and tells an unauthenticated caller which requests were well-formed.

A capability’s name is one segment doing five jobs — the add argument, the migration namespace, the table prefix, the error domain, the audit domain. Never invent a sixth spelling.

No secret is ever printed, logged, or put in an audit event.

Bindings first, REST second. The REST client needs an account token, which a Worker has neither of and should not.

Errors carry a code and params

Never a message alone.

"That board does not exist: weekly." is one string a client can only print. leaderboard/board_not_found with { board: "weekly" } is a sentence any client can rewrite in any language — and the English still arrives on the wire.

message is English permanently, and detail is stripped by the HTTP codec.

Tests are split by runtime, and that split is the argument

Worker tests run inside workerd against a real D1 and a real KV through Miniflare. Everything else runs in Node.

A test that mocks D1 proves the mock works.

Keep the harness’s compatibility date with the Worker’s. A harness pinned older than the Worker it is evidence about is not evidence — that cost a full day on a phantom failure only the harness could produce.

Documentation is part of the change

Every CLI command page carries the same six sections, and a gate holds each page to naming every key its --json payload emits.

Every declared admin route is checked against the router that actually mounted, in both directions, by the capability’s own contract test.

A route is not finished until the OpenAPI document can say something true about it. describeRoute({ summary, verification, responses }) first on the route line, each success response a Zod object in the capability’s src/http/responses.ts, every request part read through validate(target, Schema), and every field .describe()d. The capability’s contract test fails on a route or a field that is not.

A route change regenerates docs/openapi.generated.json in the same commit, and a frame change regenerates docs/asyncapi.generated.json. Both are composed from each package’s build, so write them after one. One command writes both, and CI fails while either is stale:

bun run build && bun run kit-contract

A socket is the same, with frames for routes. A capability that serves one declares it on Capability.sockets, with a described Zod schema for every frame it sends and accepts, and parses every incoming frame with that schema. How a frame may change at all is the socket contract.

The rule about comments

A comment says only what is true of the code now, and only what the code, a type, a test or a lint rule cannot say. No issue numbers, no names and dates, no account of what the code used to do. That history belongs in the commit and the issue, where it stays accurate.

A gate holds it. packages/cli/src/ci/commentHistory.test.ts counts the issue references and attributions in each file’s comments against the committed comment-history.jsonc, and fails when a count rises or a file outside the baseline gains one. When you clean a file, lower the baseline to match; the command refuses to raise a count:

bun scripts/comment-history.ts

Write the limits down

A limit nobody recorded reads as a limit nobody saw.

The races that cannot be closed, the platform constraints, the things a vendor does not expose — those sentences are the useful ones, and they belong beside the code rather than in somebody’s memory.

The prose rule

American English, including in comments. Not a style preference: the site ships en-us metadata, so a page using a British spelling contradicts its own header.

A catalog file written in another language declares itself in its head, within the first 25 lines, in one published spelling — and that marker exempts the file’s quoted values, not the file.

Before you commit

Run the checks and gate on the exit code, never on grepping the output.

How a change lands

An issue arrives on a form — Bug report or Feature request, at github.com/pithy-sh/pithy. Blank issues are off, because the form asks what a maintainer needs to reproduce a bug. A vulnerability is never an issue: report it privately, as the repository’s SECURITY.md says.

An issue filed by the Claude Code plugin is labeled for you. /report-kit-gap files from the adopter’s own account and ends every body with Filed with the pithy plugin for Claude Code., and a workflow applies from: pithy-plugin and needs-triage. The line grants no trust, since anybody can type it; all it buys is two labels that ask a maintainer to look.

A pull request merges into main when three things hold, and GitHub enforces all of them: the CI check is green on a branch up to date with main, one maintainer has approved the change, and every review conversation is resolved. A push after an approval dismisses it, so the approval is of the diff that merges.

You do not keep your branch up to date — we do. When we merge, we bring your branch up to date with main ourselves, and CI runs again. That needs Allow edits by maintainers left on, which GitHub sets by default. A fork owned by an organization cannot allow it, so there we ask you to merge main yourself. Otherwise we ask you to act only when main conflicts with your change, and we name the files.

Your first pull request’s CI run waits for a maintainer to approve it. The run executes your code, so a maintainer reads the diff first. After that it runs on every push.

Link the issue it closes, add a test that fails without the change, and add a changeset when it ships in a package. A fix for a platform CI does not fully cover — macOS, or most of Windows — needs the command, the shell and the output before and after.

ESC