# Developer Onboarding Guide

# Developer Onboarding Guide

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## Welcome

<!-- GUIDANCE: Warm, human welcome. State who wrote this and invite questions. -->

Welcome to **{{PROJECT_NAME}}**! This guide will help you go from zero to a fully working development environment and your first contribution.

If anything in this guide is unclear or out of date, please update it as you go — good documentation is a team responsibility. Your onboarding buddy is **{{BUDDY}}** — reach out to them anytime.

**Your first week at a glance:**
- Day 1: Set up your environment and get the app running locally
- Day 2-3: Read the architecture overview, explore the codebase
- Day 4-5: Work through your first small ticket with your buddy's guidance

---

## 1. Prerequisites

### Hardware Requirements

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| CPU | {{MIN_CPU}} | {{REC_CPU}} |
| RAM | {{MIN_RAM}}GB | {{REC_RAM}}GB |
| Disk | {{MIN_DISK}}GB free | SSD with {{REC_DISK}}GB free |
| OS | {{SUPPORTED_OS}} | |

### Accounts You Need

<!-- GUIDANCE: List every account needed with how to request access. No guesswork for the new hire. -->

| Account | Why | How to Get Access |
|---------|-----|------------------|
| GitHub / GitLab | Code repository | Ask {{GITHUB_ADMIN}} |
| {{CLOUD_PROVIDER}} | Cloud resources | Request via {{CLOUD_REQUEST_PROCESS}} |
| {{CI_CD_PLATFORM}} | CI/CD pipeline | Auto-provisioned on org invite |
| {{ERROR_TRACKER}} | Error monitoring | Ask {{SENTRY_ADMIN}} |
| {{PROJECT_MGMT}} | Tickets / tasks | Ask {{PM_ADMIN}} |
| {{COMMUNICATION}} | Team communication | Ask your manager |
| Vault / Secrets | Development secrets | Ask {{VAULT_ADMIN}} |

**Expected setup time for all accounts:** {{ACCOUNT_SETUP_TIME}} days

### Access Requests

<!-- GUIDANCE: Who to contact for each access type. -->

| Access Type | Contact | Process | SLA |
|-------------|---------|---------|-----|
| GitHub organization | {{CONTACT}} | {{PROCESS}} | {{SLA}} |
| Cloud console (read-only dev) | {{CONTACT}} | {{PROCESS}} | {{SLA}} |
| VPN | {{CONTACT}} | {{PROCESS}} | {{SLA}} |
| Production read access | {{CONTACT}} | Requires security training first | {{SLA}} |

---

## 2. Development Environment Setup

### 2.1 macOS Setup

<!-- GUIDANCE: Step-by-step with exact commands. No guessing. -->

```bash
# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install {{TOOLS_LIST}}
# e.g.: brew install git node nvm docker kubectl terraform

# Install nvm (Node version manager)
brew install nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# Install required Node version
nvm install {{NODE_VERSION}}
nvm use {{NODE_VERSION}}
nvm alias default {{NODE_VERSION}}
```

### 2.2 Linux Setup

```bash
# Update package index
sudo apt update && sudo apt upgrade -y

# Install required tools
sudo apt install -y {{LINUX_TOOLS}}

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v{{NVM_VERSION}}/install.sh | bash
source ~/.bashrc

# Install required Node version
nvm install {{NODE_VERSION}}
```

### 2.3 Windows Setup

<!-- GUIDANCE: Windows usually requires WSL2. Document the setup clearly. -->

```powershell
# Enable WSL2
wsl --install

# After WSL2 is set up, follow the Linux setup instructions inside WSL2
# Recommended: Use VS Code with Remote WSL extension
```

### 2.4 Required Software & Versions

<!-- GUIDANCE: Pin exact versions to prevent "works on my machine" issues. -->

| Software | Required Version | Install |
|----------|-----------------|---------|
| Node.js | `{{NODE_VERSION}}` | `nvm install {{NODE_VERSION}}` |
| npm / yarn / pnpm | `{{PKG_MGR_VERSION}}` | Included with Node |
| Docker | `{{DOCKER_VERSION}}+` | docker.com/get-docker |
| Docker Compose | `{{COMPOSE_VERSION}}+` | Included with Docker Desktop |
| {{OTHER_TOOL}} | `{{VERSION}}` | {{INSTALL_CMD}} |

**Check your versions:**
```bash
node --version    # Should be v{{NODE_VERSION}}
docker --version  # Should be {{DOCKER_VERSION}}+
```

### 2.5 IDE Setup

**Recommended IDE:** {{IDE}} <!-- VS Code / JetBrains / Neovim -->

**Required extensions:**
```bash
# VS Code — install all recommended extensions
code --install-extension {{EXTENSION_1}}
code --install-extension {{EXTENSION_2}}
code --install-extension {{EXTENSION_3}}
# OR: Open project in VS Code → "Install recommended extensions" prompt will appear
```

**Recommended extensions:**

| Extension | Purpose |
|-----------|---------|
| {{EXT_1}} | {{PURPOSE}} |
| {{EXT_2}} | {{PURPOSE}} |
| {{EXT_3}} | {{PURPOSE}} |

### 2.6 Environment Variables

```bash
# Copy the example env file
cp .env.example .env

# Fill in your local values
# Ask your onboarding buddy for any values marked {{SECRET}}
```

**Key variables to set:**
| Variable | What to put | Where to get it |
|----------|-------------|-----------------|
| `DATABASE_URL` | `postgresql://localhost:5432/{{APP}}_dev` | Local setup |
| `{{SECRET_VAR}}` | Your dev secret | Ask {{BUDDY}} |

---

## 3. Repository Setup

```bash
# Step 1: Clone the repository
git clone {{REPO_URL}}
cd {{REPO_NAME}}

# Step 2: Install dependencies
{{INSTALL_CMD}}  # npm install / yarn / pnpm install

# Step 3: Set up the database
{{DB_SETUP_CMD}}  # e.g., npm run db:create && npm run db:migrate

# Step 4: Seed development data
{{SEED_CMD}}  # e.g., npm run db:seed

# Step 5: Configure environment (see 2.6)
cp .env.example .env
# Edit .env with your values

# Step 6: Start the application
{{DEV_CMD}}  # e.g., npm run dev

# Step 7: Open the application
open http://localhost:{{PORT}}
```

---

## 4. Architecture Overview

<!-- GUIDANCE: Link to detailed docs, but provide enough here that the developer has context. -->

**High-level architecture:** See [deployment-architecture.md](../INFRASTRUCTURE/deployment-architecture.md)

**In brief:**
- **Frontend:** {{FRONTEND_STACK}} — located in `{{FRONTEND_DIR}}`
- **Backend:** {{BACKEND_STACK}} — located in `{{BACKEND_DIR}}`
- **Database:** {{DB_ENGINE}} — schema in `{{SCHEMA_DIR}}`
- **Key external services:** {{EXTERNAL_SERVICES}}

**Codebase tour (key directories):**

| Directory | Purpose |
|-----------|---------|
| `{{DIR_1}}` | {{PURPOSE_1}} |
| `{{DIR_2}}` | {{PURPOSE_2}} |
| `{{DIR_3}}` | {{PURPOSE_3}} |
| `{{DIR_4}}` | {{PURPOSE_4}} |

---

## 5. Key Documentation Links

<!-- GUIDANCE: All the important docs in one place. Update this as new docs are created. -->

| Document | Link | Purpose |
|----------|------|---------|
| Architecture | [deployment-architecture.md](../INFRASTRUCTURE/deployment-architecture.md) | How the system is structured |
| API Documentation | {{API_DOCS_LINK}} | API reference |
| Design System | {{DESIGN_SYSTEM_LINK}} | UI components |
| Coding Standards | [coding-standards.md](./coding-standards.md) | How we write code |
| Test Strategy | [test-strategy.md](../TESTING/test-strategy.md) | How we test |
| CI/CD Pipeline | [cicd-pipeline.md](../INFRASTRUCTURE/cicd-pipeline.md) | How deployments work |
| Tech Decisions (ADRs) | {{ADR_DIR}} | Why we made key decisions |

---

## 6. Coding Standards Reference

**Standards document:** [coding-standards.md](./coding-standards.md)

**Quick reference:**
- **Commit messages:** Conventional Commits format (`feat:`, `fix:`, `docs:`, etc.)
- **Branch naming:** `{{BRANCH_FORMAT}}` (e.g., `feature/TICKET-123-short-description`)
- **PR size:** Aim for < {{PR_SIZE}} lines changed per PR
- **Testing requirement:** All PRs require tests for new code

---

## 7. Git Workflow & Branching Strategy

```bash
# Create a feature branch
git checkout -b feature/{{TICKET}}-description

# Make changes, then commit
git add {{FILES}}
git commit -m "feat({{SCOPE}}): describe what you did"

# Push your branch
git push origin feature/{{TICKET}}-description

# Open a PR via GitHub/GitLab UI
```

**Branching strategy:** {{STRATEGY}} — see [CI/CD Pipeline](../INFRASTRUCTURE/cicd-pipeline.md)

**PR requirements:**
1. Title follows format: `type(scope): description`
2. PR description filled in (template auto-loaded)
3. Tests included for new code
4. CI pipeline passing before requesting review
5. At least {{REVIEW_COUNT}} reviewer(s) approved

---

## 8. First PR Checklist

<!-- GUIDANCE: This is your milestone — getting the first PR merged confirms the setup is working. -->

Your first PR goal: A small, low-risk change to confirm everything works end-to-end.

- [ ] Development environment running locally
- [ ] Can run the full test suite: `{{TEST_CMD}}`
- [ ] All tests passing locally
- [ ] First branch created following naming convention
- [ ] Change made (start small — a doc fix or minor improvement is perfect)
- [ ] Tests written for any logic change
- [ ] PR opened with filled description
- [ ] CI pipeline passing on your PR
- [ ] Review requested from your onboarding buddy
- [ ] First PR merged 🎉

---

## 9. Team Rituals & Meetings

<!-- GUIDANCE: Help the new developer integrate into team rhythms quickly. -->

| Meeting | Frequency | When | Purpose | Required |
|---------|-----------|------|---------|---------|
| Daily standup | Daily | {{TIME}} | Status, blockers | Yes |
| Sprint planning | {{SPRINT_FREQ}} | {{TIME}} | Plan upcoming sprint | Yes |
| Sprint review | {{SPRINT_FREQ}} | {{TIME}} | Demo completed work | Yes |
| Retrospective | {{SPRINT_FREQ}} | {{TIME}} | Process improvement | Yes |
| Architecture review | Monthly | {{TIME}} | Tech decisions | Optional |
| Social / team coffee | {{SOCIAL_FREQ}} | {{TIME}} | Team building | Encouraged |

---

## 10. Communication Channels

<!-- GUIDANCE: Where to go for what. -->

| Channel | Platform | Purpose |
|---------|----------|---------|
| `#{{GENERAL_CHANNEL}}` | {{PLATFORM}} | General team communication |
| `#{{DEV_CHANNEL}}` | {{PLATFORM}} | Developer discussions, code help |
| `#{{INCIDENTS_CHANNEL}}` | {{PLATFORM}} | Incident response |
| `#{{DEPLOYMENTS_CHANNEL}}` | {{PLATFORM}} | Deployment notifications |
| Direct message | {{PLATFORM}} | Quick questions to teammates |
| {{EMAIL_LIST}}` | Email | Formal announcements |

**Rule:** Default to public channels over DMs. Questions asked in channels help the whole team.

---

## 11. Key Contacts

<!-- GUIDANCE: Who to go to for what. -->

| Role | Name | Contact | Help With |
|------|------|---------|-----------|
| Onboarding Buddy | {{BUDDY}} | {{CONTACT}} | Everything in the first week |
| Tech Lead | {{TECH_LEAD}} | {{CONTACT}} | Technical decisions, architecture |
| Engineering Manager | {{ENG_MGR}} | {{CONTACT}} | Career, process, team |
| DevOps / Platform | {{DEVOPS}} | {{CONTACT}} | Infrastructure, deployment, CI |
| QA Lead | {{QA_LEAD}} | {{CONTACT}} | Testing questions |

---

## Related Documents

- [Local Development Setup](./local-development-setup.md)
- [Coding Standards](./coding-standards.md)
- [Developer Offboarding Guide](./developer-offboarding-guide.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |