Local Setup Guide
ℹ️
The Test of Readiness
If you can't run the project locally, you can't contribute to it. This step is non-negotiable.
The Local Setup Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ LOCAL SETUP PIPELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ FORK │───►│ CLONE │───►│ INSTALL │───►│ CONFIG │ │
│ │ │ │ │ │ DEPS │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Copy repo Get code npm install .env files │
│ to your locally pip install config files │
│ account go mod databases │
│ │
│ │ │
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ BUILD │───►│ RUN │───►│ TESTS │───►│ UPSTREAM │ │
│ │ │ │ │ │ │ │ REMOTE │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Compile Start dev Run test Add upstream │
│ if needed server suite remote │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Step 1: Fork the Repository
Go to the project's GitHub page
Navigate to the repository you want to contribute to.
Click the Fork button
Top right corner. This creates a copy in YOUR GitHub account.
Wait for fork to complete
GitHub will redirect you to your fork: github.com/YOUR-USERNAME/project-name
┌─────────────────────────────────────────────────────────────────┐
│ FORK ARCHITECTURE │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ ORIGINAL REPO (UPSTREAM) │ │
│ │ github.com/org/project │ │
│ │ │ │
│ │ main ─────────────────────────────────► │ │
│ └────────────────────┬────────────────────────────┘ │
│ │ Fork │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ YOUR FORK (ORIGIN) │ │
│ │ github.com/you/project │ │
│ │ │ │
│ │ main ─────────────────────────────────► │ │
│ └────────────────────┬────────────────────────────┘ │
│ │ Clone │
│ ▼ │
│ ┌─────────────────────────────────────────────────┐ │
│ │ LOCAL CLONE │ │
│ │ ~/projects/project │ │
│ │ │ │
│ │ main ─────────────────────────────────► │ │
│ │ └── feature-branch ──────────────► │ │
│ └─────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘Step 2: Clone Your Fork
# Clone your fork (not the original!)
git clone git@github.com:YOUR-USERNAME/project-name.git
# Navigate into the project
cd project-name⚠️
Clone YOUR Fork
Clone from YOUR fork (your-username/project), not the original (org/project). You won't have push access to the original.
Step 3: Add Upstream Remote
This lets you sync with the original repository:
# Add the original repo as "upstream"
git remote add upstream git@github.com:original-org/project-name.git
# Verify remotes
git remote -v
# Should show:
# origin git@github.com:YOUR-USERNAME/project.git (fetch)
# origin git@github.com:YOUR-USERNAME/project.git (push)
# upstream git@github.com:original-org/project.git (fetch)
# upstream git@github.com:original-org/project.git (push)Step 4: Install Dependencies
JavaScript/TypeScript
# Using npm
npm install
# Using yarn
yarn install
# Using pnpm (preferred for monorepos)
pnpm install
# Using bun
bun installPython
# Create virtual environment
python -m venv venv
# Activate it
source venv/bin/activate # Linux/macOS
# or
.\venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# or for development
pip install -e ".[dev]"Rust
cargo buildGo
go mod downloadStep 5: Environment Configuration
Many projects require environment variables:
# Check if there's an example env file
ls -la | grep -i env
# Common names:
# .env.example
# .env.sample
# .env.template
# Copy and configure
cp .env.example .env
# Edit with your editor
code .env # or vim .env💡
Check docs for env setup
README or CONTRIBUTING.md usually explains required environment variables.
Step 6: Build (If Required)
Check if build is needed
# Check package.json scripts
cat package.json | grep -A 20 '"scripts"'
# Common build commands:
npm run build
yarn build
pnpm buildWatch mode for development
# Continuous rebuild during development
npm run dev
# or
npm run watchStep 7: Run the Project
Step 8: Run Tests
⚠️
Tests Must Pass Before PR
If tests fail on a clean clone, it's a project issue. But YOUR changes must not break tests.
# JavaScript
npm test
npm run test:watch # Interactive mode
# Python
pytest
python -m unittest discover
# Rust
cargo test
# Go
go test ./...Common Setup Issues
┌─────────────────────────────────────────────────────────────────────────────┐
│ TROUBLESHOOTING GUIDE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PROBLEM: npm install fails │
│ ───────────────────────────── │
│ → Check Node version (nvm use or volta) │
│ → Delete node_modules and package-lock.json, retry │
│ → Check for native dependencies requiring build tools │
│ │
│ PROBLEM: "Module not found" │
│ ───────────────────────────── │
│ → Did you run npm install? │
│ → Is the import path correct? │
│ → Check if module is in dependencies (not just devDependencies) │
│ │
│ PROBLEM: Python import errors │
│ ───────────────────────────── │
│ → Is virtualenv activated? │
│ → Did you install with pip install -e .? │
│ → Check PYTHONPATH │
│ │
│ PROBLEM: Docker errors │
│ ───────────────────────────── │
│ → Is Docker running? │
│ → docker-compose down && docker-compose up --build │
│ → Check port conflicts │
│ │
│ PROBLEM: Database connection fails │
│ ───────────────────────────── │
│ → Is database service running? │
│ → Check .env connection string │
│ → Run migrations if needed │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Keeping Your Fork Updated
Before starting new work, always sync with upstream:
# Fetch upstream changes
git fetch upstream
# Switch to main
git checkout main
# Merge upstream changes
git merge upstream/main
# Push to your fork
git push origin mainSetup Verification Checklist
- Repository forked to my account
- Clone is from MY fork (not upstream)
- Upstream remote added
- Dependencies installed without errors
- Environment variables configured
- Project builds successfully
- Project runs locally
- All tests pass
- I can access the running application (if web)