plex-playlist/docs/DEVELOPMENT.md

Development Environment Setup and Workflow

This document outlines how to set up your development environment and work with the plex-playlist project.

Table of Contents

1. Quick Start
2. Development Environment Setup
3. Git Workflow
4. Pre-commit Hooks
5. Manual Tool Usage
6. CI/CD Pipeline
7. Branch Protection and Merge Requirements

Quick Start

# Clone the repository
git clone ssh://git@dogar.darkhelm.org:2222/DarkHelm.org/plex-playlist.git
cd plex-playlist

# Start development environment
docker compose -f compose.dev.yml up -d

# Set up pre-commit (recommended)
pip install pre-commit
pre-commit install

# Create a feature branch and start developing
git checkout -b feature/your-feature-name

Development Environment Setup

Local Development with Docker Compose

The project uses compose.dev.yml for local development, which provides:

• Backend: FastAPI application with hot reload
• Frontend: Vite development server with hot module replacement
• Database: PostgreSQL with persistent data
• Development Tools: Pre-configured with all necessary dependencies

# Start all services
docker compose -f compose.dev.yml up -d

# View logs
docker compose -f compose.dev.yml logs -f

# Stop services
docker compose -f compose.dev.yml down

# Rebuild after dependency changes
docker compose -f compose.dev.yml up -d --build

Service Access

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• API Documentation: http://localhost:8000/docs
• Database: localhost:5432 (user: plex, password: see secrets/postgres_password)

Git Workflow

Branch Strategy

The project follows a feature branch workflow with strict main branch protection:

1. Main Branch: Always deployable, protected from direct commits
2. Feature Branches: All work done in feature branches (feature/feature-name)
3. Pull Requests: Required for all changes to main

Creating a Feature Branch

# Ensure you're on main and up to date
git checkout main
git pull origin main

# Create and switch to feature branch
git checkout -b feature/your-feature-name

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

Making Changes

# Make your changes
# ... edit files ...

# Stage and commit
git add .
git commit -m "feat: add new playlist functionality"

# Push changes
git push

Creating a Pull Request

1. Push your feature branch to the remote repository
2. Navigate to the Gitea web interface
3. Create a Pull Request from your feature branch to main
4. Ensure all CI checks pass (100% green required)
5. Request review from team members
6. Merge only after approval and passing CI

Pre-commit Hooks

Why Pre-commit is Recommended

Pre-commit hooks provide immediate feedback and prevent CI failures by running the same validation locally that runs in CI. Benefits:

• Fast Feedback: Catch issues before pushing
• Consistent Quality: Same tools and configurations as CI
• Time Saving: Avoid CI failure cycles
• Team Standards: Automatic code formatting and linting

Installation and Setup

# Install pre-commit (if not already installed)
pip install pre-commit

# Install hooks for this repository
pre-commit install

# Optionally, run on all files initially
pre-commit run --all-files

How It Works

Pre-commit automatically runs on every git commit and will:

• Format code (Prettier, Ruff)
• Check syntax (ESLint, Pyright)
• Validate files (YAML, TOML, trailing whitespace)
• Run quick tests and linting

If any hook fails, the commit is blocked until issues are fixed.

Pre-commit is Optional

While strongly recommended, pre-commit is not required because:

• CI Validation: All the same checks run in CI
• Developer Choice: Some prefer manual tool usage
• Learning: Developers can run tools individually to understand them

However, without pre-commit, you'll need to manually run tools and may face CI failures.

Manual Tool Usage

If you prefer not to use pre-commit, here's how to run each tool manually:

Backend Tools (Python)

Navigate to the backend/ directory for all backend commands.

Code Formatting

# Format code with Ruff
uv run ruff format .

# Fix auto-fixable linting issues
uv run ruff check . --fix

Type Checking

# Run Pyright type checker
uv run pyright

Testing

# Run unit tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=src --cov-report=html

# Run integration tests
uv run pytest tests/integration/

# Run doctests
uv run xdoctest src/

Documentation

# Check docstring style
uv run darglint src/

Frontend Tools (TypeScript/Vue)

Navigate to the frontend/ directory for all frontend commands.

Code Formatting

# Format code with Prettier
yarn format

# Check formatting
yarn format:check

Linting

# Run ESLint
yarn lint

# Fix auto-fixable ESLint issues
yarn lint:fix

# Check TypeScript documentation
yarn lint:tsdoc

Type Checking

# Run Vue TypeScript compiler
yarn type-check

Testing

# Run unit tests
yarn test

# Run unit tests with coverage
yarn test:coverage

# Run E2E tests
yarn test:e2e

Project-wide Tools

YAML/TOML Validation

# Check YAML files
pre-commit run check-yaml --all-files

# Check TOML files
pre-commit run check-toml --all-files

File Quality

# Fix trailing whitespace
pre-commit run trailing-whitespace --all-files

# Fix end-of-file issues
pre-commit run end-of-file-fixer --all-files

CI/CD Pipeline

Pipeline Overview

The CI/CD pipeline runs automatically on:

• Push to any branch
• Pull requests to main or develop

Pipeline Jobs

All jobs run in parallel after the setup phase:

1. Setup: Builds and pushes the CI/CD Docker image
2. Code Quality:
   • Trailing whitespace check
   • End-of-file formatting
   • YAML syntax validation
   • TOML syntax validation
3. Backend Validation:
   • Ruff formatting check
   • Ruff linting
   • Pyright type checking
   • Darglint docstring validation
   • Unit tests with coverage
   • Integration tests
   • Doctests (xdoctest)
4. Frontend Validation:
   • Prettier formatting check
   • ESLint linting
   • TypeScript compilation
   • Unit tests with coverage
   • E2E tests (Playwright)

CI/CD Design Principles

• Single Source of Truth: All CI jobs use the same pre-commit hooks as local development
• Parallel Execution: Maximum efficiency with concurrent job execution
• Fast Feedback: Jobs fail fast on first error
• Comprehensive Coverage: Every aspect of code quality is validated

Viewing CI Results

1. Navigate to your pull request in Gitea
2. Check the "Checks" tab for detailed results
3. Click on individual job names to see logs
4. All jobs must pass (100% green) before merging

Branch Protection and Merge Requirements

Main Branch Protection

The main branch is protected with the following requirements:

1. No Direct Pushes: All changes must come through pull requests
2. CI Must Pass: All CI/CD jobs must be 100% green
3. Review Required: At least one team member approval needed
4. Up-to-date Branch: Feature branch must be current with main

Merge Process

1. Create pull request from feature branch
2. Wait for all CI checks to complete successfully
3. Address any CI failures by pushing fixes to the feature branch
4. Request and receive code review approval
5. Ensure branch is up-to-date with main
6. Merge pull request (only available when all requirements met)

If CI Fails

When CI fails:

1. Check Logs: Review the failed job logs in Gitea
2. Fix Locally: Make corrections in your feature branch
3. Test Locally: Run the same tools locally or use pre-commit
4. Push Fix: Commit and push the fix
5. Wait for CI: New CI run will start automatically

Common CI Failure Resolutions

# Format code issues
pre-commit run --all-files

# Type errors (backend)
cd backend && uv run pyright

# Type errors (frontend)
cd frontend && yarn type-check

# Test failures (backend)
cd backend && uv run pytest

# Test failures (frontend)
cd frontend && yarn test:coverage

# E2E test failures (frontend)
cd frontend && yarn test:e2e

Best Practices

Development Workflow

1. Always use feature branches - never commit directly to main
2. Keep branches small - easier to review and merge
3. Write descriptive commit messages - helps with project history
4. Run tests locally - catch issues before pushing
5. Use pre-commit - saves time and ensures quality

Code Quality

1. Follow existing patterns - maintain consistency
2. Write tests for new features - maintain coverage thresholds
3. Add docstrings - especially for public APIs
4. Type annotations - required for all Python functions
5. Meaningful variable names - self-documenting code

Performance Tips

1. Use Docker efficiently - leverage layer caching
2. Run specific tests - don't always run full suite during development
3. Parallel development - multiple developers can work simultaneously
4. Resource monitoring - watch Docker memory usage on constrained systems

---

For questions or issues with the development environment, please create an issue in the project repository or contact the development team.