Developer onboarding

Developer Onboarding

Get a new developer from a fresh clone to a running local environment and a passing test run in the fewest, clearest steps possible, without hidden assumptions.

1. Prerequisites and environment requirements

• State the exact runtime, compiler and package manager versions from the repository's manifests (engines, .nvmrc, .tool-versions, composer.json, Cargo.toml, pyproject.toml).
• List required system dependencies and external services (databases, Redis, CLI tools, OS-specific build tools) and separate what is strictly required for local development from optional integrations.

2. Step-by-step setup to first green run

Write the setup sequence in the exact order a clean machine needs:

1. Install dependencies: exact command and working directory (npm install, composer install).
2. Configure environment: how to create local config (for example copying .env.example to .env), which variables must be set for local startup vs. which have working defaults, and where local data/tokens are stored.
3. Prepare data and build: database migrations, seeders or required build steps (npm run build -w ...) that must run before starting the app.
4. Start the application: the command(s) to launch the server, UI dev server and background workers, plus the exact URL, port and health check that confirm it is running.
5. Verify with tests: the command to run the fast test suite, typecheck and linter so the developer knows their checkout is healthy before making changes.

3. Configuration reference

For every configuration key or environment variable a developer touches:

• State its purpose, type/format, default value in code, when it takes effect (startup vs. build time), and a safe example value.
• Flag settings that change security boundaries, wipe data or connect to external accounts.

4. Common first-run pitfalls

• Document the 3–5 most likely setup failures evidenced by the codebase (port conflicts, missing native toolchains, unbuilt workspace packages, missing auth tokens, stale database state) and the exact command to fix each.

Before you finish

• Runtime and tool versions match the repository's manifests and lockfiles.
• Setup steps run in order from a clean checkout without missing intermediate commands.
• Every environment variable's purpose, default and effect are checked against the code.
• The reader has a clear verification check for both the running app and the test suite.
• Common setup failures have concrete remedies.