Developer Onboarding

Developer Onboarding

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Create comprehensive onboarding documentation that helps new developers quickly set up their development environment, understand the codebase, and start contributing effectively.

When to Use

• New developer onboarding
• README file creation
• Contributing guidelines
• Development environment setup
• Architecture overview docs
• Code style guides
• Git workflow documentation
• Testing guidelines
• Deployment procedures

Quick Start

Minimal working example:

````markdown

Project Name

Brief project description (1-2 sentences explaining what this project does).

   

Table of Contents

• Features
• Quick Start
• Prerequisites
• Installation
• Configuration
• Development
• Testing
• Deployment
• Architecture
• Contributing
• License

Features

// ... (see reference guides for full implementation)

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [Clone the Repository](references/clone-the-repository.md) | Clone the Repository, Install Dependencies |
| [Set Up Environment Variables](references/set-up-environment-variables.md) | Set Up Environment Variables |
| [Database Setup](references/database-setup.md) | Database Setup, Verify Installation |
| [Project Structure](references/project-structure.md) | Project Structure |
| [Available Scripts](references/available-scripts.md) | Available Scripts |
| [Code Style](references/code-style.md) | Code Style |
| [Git Workflow](references/git-workflow.md) | Git Workflow |
| [Running Tests](references/running-tests.md) | Running Tests |
| [Writing Tests](references/writing-tests.md) | Writing Tests |

## Best Practices

### ✅ DO

- Start with a clear, concise project description
- Include badges for build status, coverage, etc.
- Provide a quick start section
- Document all prerequisites clearly
- Include troubleshooting section
- Keep README up-to-date
- Use code examples liberally
- Add architecture diagrams
- Document environment variables
- Include contribution guidelines
- Specify code style requirements
- Document testing procedures

### ❌ DON'T

- Assume prior knowledge
- Skip prerequisite documentation
- Forget to update after major changes
- Use overly technical jargon
- Skip example code
- Ignore Windows/Mac/Linux differences
- Forget to document scripts

Available Scripts

Available Scripts

# Development
npm run dev              # Start dev server with hot reload
npm run dev:debug        # Start with debugger attached

# Building
npm run build            # Build for production
npm run build:watch      # Build and watch for changes

# Testing
npm test                 # Run all tests
npm run test:unit        # Run unit tests only
npm run test:integration # Run integration tests
npm run test:e2e         # Run e2e tests
npm run test:watch       # Run tests in watch mode
npm run test:coverage    # Generate coverage report

# Linting & Formatting
npm run lint             # Run ESLint
npm run lint:fix         # Fix ESLint errors
npm run format           # Format code with Prettier
npm run format:check     # Check formatting

# Database
npm run db:migrate       # Run migrations
npm run db:migrate:undo  # Undo last migration
npm run db:seed          # Seed database
npm run db:reset         # Reset database (drop, create, migrate, seed)

# Other
npm run clean            # Clean build artifacts
npm start                # Start production server

Clone the Repository

Clone the Repository

git clone https://github.com/username/repo.git
cd repo

Install Dependencies

# Install all dependencies
npm install

# Or use yarn
yarn install

# Or use pnpm
pnpm install

Code Style

Code Style

We use ESLint and Prettier for consistent code style:

ESLint Config:

// .eslintrc.js
module.exports = {
  extends: ["airbnb-base", "prettier"],
  plugins: ["prettier"],
  rules: {
    "prettier/prettier": "error",
    "no-console": process.env.NODE_ENV === "production" ? "error" : "off",
    "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
  },
};

Prettier Config:

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "es5",
  "printWidth": 100,
  "tabWidth": 2
}

Database Setup

Database Setup

# Create database
createdb your_database_name

# Run migrations
npm run db:migrate

# Seed database with sample data (optional)
npm run db:seed

Verify Installation

# Run tests to verify setup
npm test

# Start development server
npm run dev

If everything is set up correctly, you should see:

✓ Server running on http://localhost:3000
✓ Database connected
✓ Redis connected

Git Workflow

Git Workflow

We follow the Git Flow branching model:

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push to remote
git push origin feature/your-feature-name

# Create pull request on GitHub

Branch Naming Convention:

• feature/ - New features
• bugfix/ - Bug fixes
• hotfix/ - Urgent production fixes
• refactor/ - Code refactoring
• docs/ - Documentation updates

Commit Message Convention:

We use Conventional Commits:

type(scope): subject

body

footer

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

feat(auth): add OAuth2 authentication
fix(api): resolve race condition in order processing
docs(readme): update installation instructions

Project Structure

Project Structure

.
├── src/
│   ├── api/              # API routes
│   │   ├── controllers/  # Route controllers
│   │   ├── middlewares/  # Express middlewares
│   │   └── routes/       # Route definitions
│   ├── config/           # Configuration files
│   ├── models/           # Database models
│   ├── services/         # Business logic
│   ├── utils/            # Utility functions
│   └── app.js            # Express app setup
├── tests/
│   ├── unit/             # Unit tests
│   ├── integration/      # Integration tests
│   └── e2e/              # End-to-end tests
├── scripts/              # Utility scripts
├── docs/                 # Documentation
├── .env.example          # Environment template
├── .eslintrc.js          # ESLint config
├── .prettierrc           # Prettier config
├── package.json
└── README.md

Running Tests

Running Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test -- tests/unit/user.test.js

# Run tests matching pattern
npm test -- --grep "User API"

Set Up Environment Variables

Set Up Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Edit .env and configure the following:

# Application
NODE_ENV=development
PORT=3000
BASE_URL=http://localhost:3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Redis
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=7d

# External APIs
STRIPE_SECRET_KEY=sk_test_...
SENDGRID_API_KEY=SG...

# AWS (if applicable)
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret
S3_BUCKET_NAME=your-bucket

Writing Tests

Writing Tests

Unit Test Example:

// tests/unit/user.service.test.js
const { expect } = require("chai");
const UserService = require("../../src/services/user.service");

describe("UserService", () => {
  describe("createUser", () => {
    it("should create a new user", async () => {
      const userData = {
        email: "test@example.com",
        password: "password123",
        name: "Test User",
      };

      const user = await UserService.createUser(userData);

      expect(user).to.have.property("id");
      expect(user.email).to.equal(userData.email);
      expect(user.password).to.not.equal(userData.password); // Should be hashed
    });

    it("should throw error for duplicate email", async () => {
      const userData = { email: "existing@example.com" };

      await expect(UserService.createUser(userData)).to.be.rejectedWith(
        "Email already exists",
      );
    });
  });
});

Integration Test Example:

// tests/integration/auth.test.js
const request = require("supertest");
const app = require("../../src/app");

describe("Auth API", () => {
  describe("POST /api/auth/register", () => {
    it("should register a new user", async () => {
      const response = await request(app)
        .post("/api/auth/register")
        .send({
          email: "newuser@example.com",
          password: "password123",
          name: "New User",
        })
        .expect(201);

      expect(response.body).to.have.property("token");
      expect(response.body.user).to.have.property("id");
    });
  });
});

Document Title

Overview

TODO: Brief description of this document's purpose.

Prerequisites

• TODO: List prerequisites

Getting Started

TODO: Step-by-step instructions.

Configuration

TODO: Configuration details.

Examples

TODO: Add practical examples.

Troubleshooting

TODO: Common issues and solutions.

References

• TODO: Add relevant links