Contributing Guide

Welcome to YeboLearn! This guide will help you set up your development environment and make your first contribution.

Prerequisites

Required Software

Core Requirements:

Node.js 20+ (LTS version)
npm 10+ or yarn 1.22+
Git 2.30+
Docker 24+ (for local database)
PostgreSQL 15+ (via Docker)

Recommended:

VS Code with extensions:
- ESLint
- Prettier
- TypeScript
- Prisma
- GitLens
Postman or Insomnia (API testing)
GitHub CLI (optional, for easier PR management)

System Requirements

Minimum:
- CPU: 2 cores
- RAM: 8 GB
- Storage: 20 GB free

Recommended:
- CPU: 4 cores
- RAM: 16 GB
- Storage: 50 GB free (for Docker images, databases)

Getting Started

1. Clone the Repository

bash

# Clone the main repository
git clone https://github.com/yebolearn/yebolearn-platform.git
cd yebolearn-platform

# Or if you have SSH configured
git clone [email protected]:yebolearn/yebolearn-platform.git
cd yebolearn-platform

2. Install Dependencies

bash

# Install all dependencies
npm install

# This will take 2-3 minutes on first run

3. Set Up Environment Variables

bash

# Copy example environment file
cp .env.example .env

# Edit .env with your settings
# Most defaults will work for local development

Required Environment Variables:

bash

# .env
NODE_ENV=development
PORT=8080

# Database (use Docker PostgreSQL)
DATABASE_URL="postgresql://yebolearn:dev_password@localhost:5432/yebolearn_dev"

# JWT tokens (use provided dev keys)
JWT_SECRET="dev-secret-key-change-in-production"
JWT_REFRESH_SECRET="dev-refresh-secret-change-in-production"

# AI Features (get free API key from Google AI Studio)
GEMINI_API_KEY="your-gemini-api-key"

# Email (optional for local dev, uses console output)
EMAIL_PROVIDER="console"

# SMS (optional for local dev)
SMS_PROVIDER="console"

Getting API Keys:

Gemini API (Free for Development):

Visit Google AI Studio
Sign in with Google account
Create API key
Copy to GEMINI_API_KEY in .env
Free tier: 60 requests/minute (sufficient for development)

4. Set Up Database

bash

# Start PostgreSQL in Docker
npm run db:start

# This will:
# - Pull PostgreSQL 15 image (first time)
# - Start container on port 5432
# - Create database 'yebolearn_dev'

# Run migrations
npm run db:migrate

# Seed development data
npm run db:seed

# You now have:
# - 10 test students
# - 5 test teachers
# - 15 courses
# - 50 quizzes
# - Sample quiz attempts

Database Commands:

bash

# Start database
npm run db:start

# Stop database
npm run db:stop

# Reset database (drop all data)
npm run db:reset

# View database logs
npm run db:logs

# Connect to database (psql)
npm run db:console

5. Start Development Server

bash

# Start backend server (port 8080)
npm run dev

# Server will auto-reload on file changes

Separate terminal for frontend (if applicable):

bash

# Start frontend dev server (port 3000)
cd frontend
npm run dev

6. Verify Setup

Test API:

bash

# Health check
curl http://localhost:8080/health

# Expected response:
{
  "status": "healthy",
  "version": "2.5.0",
  "checks": {
    "database": { "status": "healthy", "latency": "12ms" }
  }
}

Test Authentication:

bash

# Login with test account
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "password123"
  }'

# Expected: JWT token

Run Tests:

bash

# Run all tests
npm test

# Expected: All tests passing

Development Workflow

1. Pick a Task

Option A: From Linear (Assigned Work)

Check your Linear dashboard
Find task assigned to you
Move to "In Progress"

Option B: From GitHub Issues (Open Source)

Browse GitHub Issues
Look for good-first-issue label
Comment "I'd like to work on this"
Wait for assignment

Option C: Find a Bug

Use the platform locally
Find a bug
Create issue in GitHub/Linear
Get approval before starting

2. Create Feature Branch

bash

# Update dev branch
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/quiz-timer-fix

# Branch naming:
# - feature/description (new feature)
# - fix/description (bug fix)
# - refactor/description (code improvement)
# - docs/description (documentation)

3. Make Changes

Development Loop:

bash

# 1. Make code changes
# Edit files in your IDE

# 2. Run tests frequently
npm test -- --watch

# 3. Run linter
npm run lint

# 4. Format code
npm run format

# 5. Test manually
# Use Postman/browser to verify

Best Practices:

typescript

// Write tests as you code
describe('QuizTimer', () => {
  it('should countdown from initial time', () => {
    const timer = new QuizTimer(60);
    expect(timer.remaining).toBe(60);

    timer.tick();
    expect(timer.remaining).toBe(59);
  });
});

// Then implement
export class QuizTimer {
  constructor(private duration: number) {}

  tick() {
    this.duration--;
  }

  get remaining() {
    return this.duration;
  }
}

4. Commit Changes

Commit Message Format:

bash

# Use conventional commits
git commit -m "feat(quiz): add countdown timer to quiz page

- Display remaining time prominently
- Warn when 5 minutes remaining
- Auto-submit when time expires
- Add tests for timer logic

Fixes #234"

Commit Best Practices:

bash

# DO: Small, focused commits
git commit -m "feat: add timer component"
git commit -m "feat: integrate timer with quiz page"
git commit -m "test: add timer tests"

# DON'T: Large, unfocused commits
git commit -m "update quiz page" # What changed?

5. Push and Create Pull Request

bash

# Push your branch
git push -u origin feature/quiz-timer-fix

# Create PR via GitHub UI or CLI
gh pr create --title "Add countdown timer to quiz page" \
  --body "$(cat <<EOF
## Summary
Adds a countdown timer to quiz pages to help students manage their time.

## Changes
- Created QuizTimer component
- Integrated timer with quiz page
- Added warning at 5 minutes
- Auto-submit when time expires

## Testing
- [x] Unit tests added
- [x] Manually tested in dev environment
- [x] Tested edge cases (pause, resume, expire)

## Screenshots
[Add screenshot of timer in action]

Fixes #234
EOF
)"

Pull Request Checklist:

markdown

Before creating PR:
- [ ] All tests passing (`npm test`)
- [ ] Linting passing (`npm run lint`)
- [ ] Code formatted (`npm run format`)
- [ ] No console.log statements
- [ ] Documentation updated (if needed)
- [ ] Self-reviewed code
- [ ] Tested manually in dev environment

PR Description includes:
- [ ] Summary of changes
- [ ] Why the change was made
- [ ] Testing performed
- [ ] Screenshots (if UI changes)
- [ ] Related issue linked (Fixes #123)

6. Address Review Feedback

bash

# Make requested changes
# Edit files based on review comments

# Commit changes
git commit -m "fix: address review feedback

- Rename timer variable for clarity
- Add error handling for edge case
- Improve test coverage"

# Push updates
git push origin feature/quiz-timer-fix

# PR will update automatically

7. Merge

Once approved:

Ensure CI is green
Squash and merge via GitHub
Delete feature branch

Common Development Tasks

Running Tests

bash

# All tests
npm test

# Watch mode (auto-rerun on changes)
npm test -- --watch

# Specific test file
npm test -- quiz-timer.test.ts

# With coverage
npm test -- --coverage

# Only changed files
npm test -- --onlyChanged

# Update snapshots
npm test -- -u

Database Tasks

bash

# Create new migration
npm run db:migrate:create add_quiz_timer_field

# Run migrations
npm run db:migrate

# Rollback last migration
npm run db:migrate:rollback

# Reset database (careful!)
npm run db:reset

# Seed test data
npm run db:seed

# Open database console
npm run db:console

Code Quality

bash

# Lint code
npm run lint

# Fix auto-fixable lint issues
npm run lint:fix

# Format code with Prettier
npm run format

# Type check
npm run type-check

# Run all quality checks
npm run quality

Building

bash

# Build for production
npm run build

# Build and run locally
npm run build && npm start

# Check bundle size
npm run build -- --analyze

Development Tips

VS Code Configuration

Recommended Settings (.vscode/settings.json):

json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Recommended Extensions:

json

{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "prisma.prisma",
    "ms-azuretools.vscode-docker",
    "eamodio.gitlens"
  ]
}

Debugging

VS Code Debug Configuration (.vscode/launch.json):

json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug API",
      "runtimeArgs": ["-r", "ts-node/register"],
      "args": ["src/server.ts"],
      "env": {
        "NODE_ENV": "development"
      },
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/jest/bin/jest",
      "args": ["--runInBand"],
      "console": "integratedTerminal"
    }
  ]
}

Hot Reload

bash

# Backend auto-reloads on changes
npm run dev

# If changes not reflecting:
# 1. Check for TypeScript errors
# 2. Restart dev server
# 3. Clear node_modules and reinstall

Database GUI

Recommended: Prisma Studio

bash

# Open Prisma Studio (database GUI)
npx prisma studio

# Opens at http://localhost:5555
# Browse and edit data visually

Alternative: pgAdmin

Download from pgadmin.org
Connect to localhost:5432
Database: yebolearn_dev
User: yebolearn
Password: dev_password

Troubleshooting

Common Issues

Issue: Cannot connect to database

bash

# Check if database is running
docker ps

# If not running, start it
npm run db:start

# Check logs for errors
npm run db:logs

Issue: Port already in use

bash

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use different port
PORT=8081 npm run dev

Issue: Module not found

bash

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

Issue: Tests failing

bash

# Run tests with more detail
npm test -- --verbose

# Run specific failing test
npm test -- failing-test.test.ts

# Update snapshots if needed
npm test -- -u

Issue: TypeScript errors

bash

# Run type check
npm run type-check

# Check specific file
npx tsc --noEmit src/file.ts

# Restart VS Code TypeScript server
# CMD+Shift+P > "TypeScript: Restart TS Server"

Getting Help

Resources:

Documentation
API Docs (when dev server running)
GitHub Discussions
Team Slack: #engineering channel

Before Asking:

Check documentation
Search existing GitHub issues
Google the error message
Try the troubleshooting steps above

When Asking:

Describe what you're trying to do
Share error messages (full stack trace)
What you've already tried
Your environment (OS, Node version, etc.)

Code Review

As an Author

Before Requesting Review:

Self-review your code
All tests passing
Linting passing
Manual testing done
Screenshots added (if UI)
Description clear

During Review:

Respond to feedback promptly
Ask for clarification if needed
Make requested changes
Re-request review after changes
Don't take feedback personally

As a Reviewer

What to Look For:

Code quality and readability
Test coverage
Performance implications
Security concerns
Edge cases
Consistency with codebase

How to Give Feedback:

Be constructive and specific
Explain the "why" behind suggestions
Distinguish between required changes and suggestions
Acknowledge good work
Provide examples when helpful

Review Etiquette:

Review within 4 hours (same business day)
Start with positive feedback
Be respectful and professional
Focus on the code, not the person

First Contribution Ideas

Good First Issues

Look for these labels on GitHub:

good-first-issue: Perfect for first contribution
beginner-friendly: Simple tasks
documentation: Improve docs
bug: Fix a known issue

Suggested First Tasks

1. Fix a Typo (10 minutes)

Find typo in documentation
Fix it
Create PR
Great for learning workflow

2. Add a Test (30 minutes)

Find function without tests
Write unit test
Create PR
Learn testing practices

3. Update Documentation (1 hour)

Find outdated docs
Update with current info
Add examples
Create PR

4. Fix a Small Bug (2 hours)

Pick bug from issues
Reproduce locally
Write failing test
Fix bug
Create PR

Coding Standards

See detailed Coding Standards document.

Quick Reference:

typescript

// Use TypeScript, not JavaScript
export function gradeQuiz(answers: Answer[]): number { }

// Use conventional commits
git commit -m "feat(quiz): add timer functionality"

// Write tests
describe('QuizTimer', () => {
  it('should count down', () => { });
});

// Format with Prettier (automatic on save)
// Lint with ESLint (automatic)

Release Process

As a Contributor:

You don't need to worry about releases
Your merged PR will be included in next release
Bi-weekly release cycle

Release Timeline:

Sprint ends: Thursday
Release to production: Thursday 10 AM
Your feature goes live: Same day
Announce in team Slack

Recognition

Contributors Acknowledged:

Name in CONTRIBUTORS.md
Shoutout in release notes
Credit in feature announcements
Listed on website (for significant contributions)

Questions?

Need Help?

Read the documentation
Ask in GitHub Discussions
Reach out in Slack #engineering
Email: [email protected]

Want to Contribute More?

Join our contributor calls (monthly)
Become a maintainer (after 5+ quality PRs)
Help with code reviews
Mentor other contributors

Development Workflow - Daily development process
Coding Standards - Code quality guidelines
Testing Strategy - Testing approach
Git Conventions - Git and PR guidelines

Welcome to the YeboLearn team! We're excited to have you contribute.

Contributing Guide ​

Prerequisites ​

Required Software ​

System Requirements ​

Getting Started ​

1. Clone the Repository ​

2. Install Dependencies ​

3. Set Up Environment Variables ​

4. Set Up Database ​

5. Start Development Server ​

6. Verify Setup ​

Development Workflow ​

1. Pick a Task ​

2. Create Feature Branch ​

3. Make Changes ​

4. Commit Changes ​

5. Push and Create Pull Request ​

6. Address Review Feedback ​

7. Merge ​

Common Development Tasks ​

Running Tests ​

Database Tasks ​

Code Quality ​

Building ​

Development Tips ​

VS Code Configuration ​

Debugging ​

Hot Reload ​

Database GUI ​

Troubleshooting ​

Common Issues ​

Getting Help ​

Code Review ​

As an Author ​

As a Reviewer ​

First Contribution Ideas ​

Good First Issues ​

Suggested First Tasks ​

Coding Standards ​

Release Process ​

Recognition ​

Questions? ​

Related Documentation ​

Contributing Guide

Prerequisites

Required Software

System Requirements

Getting Started

1. Clone the Repository

2. Install Dependencies

3. Set Up Environment Variables

4. Set Up Database

5. Start Development Server

6. Verify Setup

Development Workflow

1. Pick a Task

2. Create Feature Branch

3. Make Changes

4. Commit Changes

5. Push and Create Pull Request

6. Address Review Feedback

7. Merge

Common Development Tasks

Running Tests

Database Tasks

Code Quality

Building

Development Tips

VS Code Configuration

Debugging

Hot Reload

Database GUI

Troubleshooting

Common Issues

Getting Help

Code Review

As an Author

As a Reviewer

First Contribution Ideas

Good First Issues

Suggested First Tasks

Coding Standards

Release Process

Recognition

Questions?

Related Documentation