Developing locally

You should be able to go from a fresh clone to a running thing in a few minutes, on your first day, without a wiki-crawl or a colleague on a call talking you through it. That holds for every repo we have, whichever product it belongs to. Fast, boring local setup is something we protect, because a slow environment is a tax every engineer pays every day. If reality doesn't match the steps, that mismatch is a bug worth fixing, not a rite of passage to endure.

The exact steps live in each repo's README, because each product has its own stack and its own way of running. This page is the bar those READMEs meet, and the why behind it.

The bar every repo meets

• One documented path from clone to running. A handful of commands in the README, copyable as written. If there are two ways to run it, say which one most people should use.
• Public tools only. No company VPN to join, no private registry to authenticate against, no package you can't install from the open internet. If a setup step ever needs an internal-only credential, we've done something wrong.
• Sensible local defaults. The common case needs no configuration. Anything you do have to set is listed, with what it's for.
• The checks run locally. Whatever CI runs before a merge, you can run on your machine before you push, with the same commands.
• The runtime version is pinned, in the repo, where your tools can read it.

What that looks like

This website is about as short as it gets. Node 24 is pinned in .nvmrc and in package.json, and then:

npm install
npm run dev        # http://localhost:3000
npm run lint
npm run typecheck

g1t has more moving parts, Rust services and a TypeScript site on Cloudflare, so its README lists more prerequisites and its contributing guide says exactly what to run before you push: the Rust tests for whatever you changed, a type check of the site, and a look at the change in a browser, because screenshots catch what type checks don't. Different stack, same bar: it's written down, it's in the repo, and it's current.

Tests

Each repo's README says how to run its tests, and we keep every suite fast on purpose, because a test suite nobody wants to run stops catching regressions, which is the whole argument in how we test. If the tests are slow enough that you're tempted to skip them, that's a real problem worth raising, not a personal failing.

When setup fights back

If you hit a wall, the fix is almost never to suffer through it quietly. Ask the team that owns the product, and once you're unstuck, improve the thing that tripped you: a clearer error, a missing check, a line in the README. The best possible outcome of a rough first setup is a pull request that makes the next person's setup smooth. We own what we build, and the developer experience is part of what we build.

Next, get your bearings with project structure.