oss-setup-dev-env

# Setup Dev Env

Get an unfamiliar repo building, running, and testing on your machine. Setup instructions are often outdated or assume knowledge you don't have. This skill systematically works through the actual requirements — not just what the README says.

## Purpose

The #1 reason contributors abandon their first OSS contribution isn't the code — it's the setup. Outdated README instructions, missing system dependencies, version mismatches, and Docker configurations that assume Linux all stop contributors cold. This skill teaches you to read the repo's actual build system, identify real requirements, and get a working development environment — even when the README is wrong.

## When to Use

- Cloning an OSS repo for the first time and setting up to develop
- The repo's setup instructions didn't work
- You need to debug why tests pass in CI but fail locally
- Setting up a repo that uses tools/build systems you're unfamiliar with
- **NOT** for setting up your own project
- **NOT** for CI debugging — use `oss-debug-ci` for that

## Prerequisites

- Repo forked and cloned
- Basic familiarity with your OS's package manager (brew, apt, etc.)
- `gh` CLI authenticated (to check CI configuration for hints)

## Process

### 1. Read the setup instructions (but don't trust them)

Start with the official instructions, but verify as you go.

```bash
# Find setup documentation
cat README.md | head -100
cat CONTRIBUTING.md docs/DEVELOPMENT.md docs/setup.md INSTALL.md 2>/dev/null | head -100

# Check when setup docs were last updated vs when code was last changed
git log --oneline -1 -- README.md CONTRIBUTING.md docs/DEVELOPMENT.md 2>/dev/null
git log --oneline -1 -- .
```

If the setup docs are 6+ months older than the latest code changes, they may be stale. Continue reading them, but verify each step against the actual build configuration.

### 2. Identify the build system and requirements

Read the actual build configuration — this is the source of truth, not the README.

```bash
# Language and package manager detection
ls package.json pnpm-lock.yaml yarn.lock package-lock.json 2>/dev/null  # Node.js
ls pyproject.toml setup.py setup.cfg requirements*.txt Pipfile 2>/dev/null  # Python
ls go.mod go.sum 2>/dev/null  # Go
ls Cargo.toml Cargo.lock 2>/dev/null  # Rust
ls Gemfile Gemfile.lock 2>/dev/null  # Ruby
ls pom.xml build.gradle build.gradle.kts 2>/dev/null  # Java/Kotlin
ls Makefile CMakeLists.txt 2>/dev/null  # Native/C/C++

# Version requirements
cat .node-version .nvmrc .python-version .ruby-version .tool-versions .mise.toml 2>/dev/null
cat package.json 2>/dev/null | grep -A 2 '"engines"'
cat pyproject.toml 2>/dev/null | grep -A 2 "python"
cat go.mod 2>/dev/null | head -3
cat rust-toolchain.toml rust-toolchain 2>/dev/null

# Docker-based development?
ls Dockerfile docker-compose.yml docker-compose.yaml .devcontainer/ 2>/dev/null

# System dependency hints
cat Makefile 2>/dev/null | head -50
cat Brewfile 2>/dev/null
```

Document:
- **Runtime**: what language, what version?
- **Package manager**: npm/pnpm/yarn? pip/uv/poetry? cargo?
- **System deps**: databases, native libraries, tools?
- **Docker**: is development Docker-based or Docker-optional?

### 3. Check CI for the real environment

CI configuration reveals what actually works — it's tested on every commit.

```bash
# Read the CI configuration
cat .github/workflows/ci.yml .github/workflows/test.yml 2>/dev/null

# What versions does CI use?
grep -A 3 "node-version\|python-version\|go-version\|rust-version" .github/workflows/*.yml 2>/dev/null

# What setup steps does CI run?
grep -A 5 "run:" .github/workflows/ci.yml 2>/dev/null | head -40

# What services does CI use? (databases, caches, etc.)
grep -A 10 "services:" .github/workflows/ci.yml 2>/dev/null
```

If the README says "use Node 18" but CI uses Node 22, use Node 22.

### 4. Install dependencies

Follow the build system, not the README.

```bash
# Node.js (detect the right package manager)
# Check for lockfiles to determine which manager
ls pnpm-lock.yaml 2>/dev/null && echo "Use: pnpm install"
ls yarn.lock 2>/dev/null && echo "Use: yarn install"
ls package-lock.json 2>/dev/null && echo "Use: npm install"

# Python
ls pyproject.toml 2>/dev/null && echo "Check: uv, pip, or poetry"
ls requirements.txt 2>/dev/null && echo "Use: pip install -r requirements.txt"

# Go
ls go.mod 2>/dev/null && echo "Use: go mod download"

# Rust
ls Cargo.toml 2>/dev/null && echo "Use: cargo build"
```

**Common failure points**:
- Wrong runtime version → use version manager (nvm, pyenv, rustup)
- Missing native dependencies → check Makefile, CI, or issue tracker for hints
- Network issues → check if the repo uses private registries
- Lockfile conflicts → use the exact package manager version CI uses

### 5. Build and run

```bash
# Find the build command
cat package.json 2>/dev/null | grep -A 10 '"scripts"' | head -15
cat Makefile 2>/dev/null | grep -E "^[a-zA-Z].*:" | head -10
cat pyproject.toml 2>/dev/null | grep -A 10 '\[tool\.' | head -15

# Common build commands
# npm run build / pnpm build / yarn build
# make build / make all
# cargo build
# go build ./...
# python -m build
```

Verify the build succeeds. If it fails, read the error carefully — most build failures are missing dependencies or version mismatches, not code issues.

### 6. Run the tests

This is the real proof that your environment works.

```bash
# Find the test command
cat package.json 2>/dev/null | grep "test"
cat Makefile 2>/dev/null | grep -E "^test.*:"
cat pyproject.toml 2>/dev/null | grep -A 5 '\[tool.pytest'

# Run tests
# npm test / pnpm test / yarn test
# make test
# pytest
# cargo test
# go test ./...
```

If tests fail:
- Compare against CI — do these tests pass there?
- Check for required services (database, Redis, etc.)
- Check for environment variables (`.env.example`, `.env.test`)
- Check for test-specific setup scripts

```bash
# Check for test environment setup
cat .env.example .env.test .env.sample 2>/dev/null
ls scrip