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.

# 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.

# 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