thrillwiki_django_no_react/shared/docs/development/workflow.md

Development Workflow

Comprehensive guide to daily development processes, Git workflow, and team collaboration for the ThrillWiki monorepo.

Overview

This document outlines the development workflow for the ThrillWiki Django + Vue.js monorepo. Following these practices ensures consistent code quality, smooth collaboration, and reliable deployments.

🏗️ Project Structure

thrillwiki-monorepo/
├── backend/                 # Django REST API
├── frontend/                # Vue.js SPA
├── shared/                  # Shared resources and scripts
├── architecture/            # Architecture documentation
└── profiles/                # Development profiles

🚀 Daily Development Workflow

1. Environment Setup

First Time Setup

# Clone the repository
git clone <repository-url>
cd thrillwiki-monorepo

# Run the automated setup script
./shared/scripts/dev/setup-dev.sh

# Or set up manually
cd backend && uv sync && cd ..
pnpm install

Daily Setup

# Start all development servers
./shared/scripts/dev/start-all.sh

# Or start individually
pnpm run dev:backend    # Django on :8000
pnpm run dev:frontend   # Vue.js on :5174

2. Development Process

Feature Development

1. Create a feature branch

   git checkout -b feature/your-feature-name
   

2. Make your changes

   • Follow the coding standards for your language
   • Write tests for new functionality
   • Update documentation as needed

3. Test your changes

   # Backend tests
   cd backend && uv run manage.py test
   
   # Frontend tests
   cd frontend && pnpm test:unit
   cd frontend && pnpm test:e2e
   
   # Full test suite
   pnpm run test
   

4. Code quality checks

   # Backend
   cd backend && uv run black . && uv run flake8 .
   
   # Frontend
   cd frontend && pnpm lint && pnpm type-check
   

Bug Fixes

1. Create a bug fix branch

   git checkout -b bugfix/issue-description
   

2. Reproduce the issue

   • Add test cases that reproduce the bug
   • Verify the fix resolves the issue

3. Implement the fix

   • Keep changes minimal and focused
   • Ensure no regressions

3. Code Review Process

Before Submitting

• All tests pass
• Code follows style guidelines
• Documentation updated
• No linting errors
• TypeScript types correct (frontend)
• Database migrations created (backend)

Pull Request Process

1. Create Pull Request

   • Use descriptive title
   • Fill out PR template
   • Link related issues
   • Add screenshots for UI changes

2. Code Review

   • At least one approval required
   • Address all review comments
   • Rebase and resolve conflicts

3. Merge Process

   • Use "Squash and merge" for feature branches
   • Use "Rebase and merge" for maintenance branches
   • Delete branch after merge

🔄 Git Workflow

Branch Naming Convention

feature/feature-name          # New features
bugfix/issue-description      # Bug fixes
hotfix/critical-issue         # Critical production fixes
refactor/component-name       # Code refactoring
docs/update-documentation     # Documentation updates
test/add-test-coverage        # Test improvements

Commit Message Format

type(scope): description

[optional body]

[optional footer]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation
• style - Code style changes
• refactor - Code refactoring
• test - Adding tests
• chore - Maintenance tasks

Examples:

feat: add park search functionality
fix: resolve ride detail page crash
docs: update API documentation
refactor: simplify park service layer

Git Workflow

Feature Development

# Start from main
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/new-park-search

# Make changes and commit
git add .
git commit -m "feat: implement park search with filters"

# Push and create PR
git push origin feature/new-park-search

Handling Conflicts

# Update your branch with latest main
git fetch origin
git rebase origin/main

# Resolve conflicts if any
# Test your changes
# Force push if needed
git push --force-with-lease origin feature/new-park-search

🧪 Testing Strategy

Backend Testing

Unit Tests

cd backend

# Run all tests
uv run manage.py test

# Run specific app tests
uv run manage.py test apps.parks

# Run with coverage
uv run coverage run manage.py test
uv run coverage report

Test Structure

backend/tests/
├── test_models.py      # Model tests
├── test_views.py       # View tests
├── test_serializers.py # Serializer tests
└── test_services.py    # Service layer tests

Frontend Testing

Unit Tests (Vitest)

cd frontend

# Run unit tests
pnpm test:unit

# Run with coverage
pnpm test:unit --coverage

# Watch mode for development
pnpm test:unit --watch

End-to-End Tests (Playwright)

cd frontend

# Run E2E tests
pnpm test:e2e

# Run specific test
pnpm test:e2e tests/park-search.spec.ts

# Debug mode
pnpm test:e2e --debug

Test Structure

frontend/src/__tests__/
├── components/         # Component tests
├── views/             # Page tests
├── services/          # Service tests
└── stores/            # Store tests

Test Coverage Requirements

• Backend: Minimum 80% coverage
• Frontend: Minimum 70% coverage
• Critical paths: 90%+ coverage

🔧 Code Quality

Backend Standards

Python Code Style

cd backend

# Format code
uv run black .

# Check style
uv run flake8 .

# Sort imports
uv run isort .

Django Best Practices

• Use Django REST Framework best practices
• Implement proper error handling
• Add database indexes for performance
• Use select_related and prefetch_related for optimization

Frontend Standards

Vue.js Best Practices

cd frontend

# Lint code
pnpm lint

# Type checking
pnpm type-check

# Format code
pnpm format

Code Organization

• Use Composition API with <script setup>
• Implement proper component structure
• Follow Vue.js style guide
• Use TypeScript for type safety

🚀 Deployment Process

Development Environment

Automated Deployment

# Deploy to development
./shared/scripts/deploy/deploy.sh dev

# Check deployment status
./shared/scripts/deploy/check-status.sh dev

Manual Deployment

1. Build frontend

   cd frontend
   pnpm build
   

2. Run backend migrations

   cd backend
   uv run manage.py migrate
   

3. Collect static files

   cd backend
   uv run manage.py collectstatic
   

Staging Environment

Deployment Checklist

• All tests pass
• Code review completed
• Documentation updated
• Database migrations tested
• Environment variables configured

Deployment Steps

# Build for staging
pnpm run build:staging

# Deploy to staging
./shared/scripts/deploy/deploy.sh staging

# Run smoke tests
./shared/scripts/deploy/smoke-test.sh staging

Production Environment

Pre-Deployment

1. Create release branch

   git checkout -b release/v1.2.3
   

2. Update version numbers

   • Update package.json
   • Update pyproject.toml
   • Tag the release

3. Final testing

   # Run full test suite
   pnpm run test
   
   # Performance testing
   ./shared/scripts/test/performance-test.sh
   

Production Deployment

# Build for production
pnpm run build:production

# Deploy to production
./shared/scripts/deploy/deploy.sh production

# Verify deployment
./shared/scripts/deploy/health-check.sh production

# Rollback if needed
./shared/scripts/deploy/rollback.sh production

🔍 Monitoring and Debugging

Development Debugging

Backend Debugging

cd backend

# Django shell for debugging
uv run manage.py shell

# Django debug toolbar (development only)
# Access at http://localhost:8000/__debug__/

# Logging
tail -f logs/django.log

Frontend Debugging

cd frontend

# Vue DevTools browser extension
# Access at http://localhost:5174/__devtools__/

# Browser developer tools
# - Console for errors
# - Network tab for API calls
# - Vue tab for component inspection

Production Monitoring

Health Checks

# API health check
curl http://localhost:8000/api/health/

# Database connectivity
./shared/scripts/monitor/db-check.sh

# Background job status
./shared/scripts/monitor/job-status.sh

Error Tracking

• Check application logs
• Monitor error rates
• Review performance metrics
• User feedback and bug reports

📚 Documentation

Documentation Updates

When to Update Documentation

• New features implemented
• API changes
• Configuration changes
• Deployment process changes

Documentation Standards

• Use clear, concise language
• Include code examples
• Provide step-by-step instructions
• Update README files
• Maintain API documentation

Documentation Files

• README.md - Main project documentation
• backend/README.md - Backend-specific documentation
• frontend/README.md - Frontend-specific documentation
• shared/docs/api/README.md - API documentation
• shared/docs/development/workflow.md - This file

🤝 Team Collaboration

Communication

Daily Standup

• What did you work on yesterday?
• What are you working on today?
• Any blockers or issues?

Code Reviews

• Be constructive and respectful
• Focus on code quality and best practices
• Suggest improvements, don't demand changes
• Explain reasoning behind suggestions

Knowledge Sharing

Documentation

• Update README files
• Document complex business logic
• Create troubleshooting guides

Pair Programming

• Share knowledge through pair programming
• Rotate team members on different parts of the system
• Cross-train on both backend and frontend

🛠️ Development Tools

Essential Tools

Version Control

• Git - Version control system
• GitHub - Repository hosting and collaboration
• GitHub Actions - CI/CD pipeline

Code Quality

• ESLint - JavaScript/TypeScript linting
• Prettier - Code formatting
• Black - Python code formatting
• Flake8 - Python linting

Testing

• Vitest - Frontend unit testing
• Playwright - E2E testing
• pytest - Backend testing

Development Environment

IDE Configuration

• VSCode with recommended extensions
• Vue Language Features extension
• Python extension
• Prettier extension

Local Development

• Docker for consistent environments
• direnv for environment variables
• nodenv for Node.js version management

🚨 Emergency Procedures

Critical Issues

Production Outage

1. Assess the situation

   • Identify the scope of the issue
   • Determine impact on users

2. Communication

   • Notify team members
   • Update status page if applicable

3. Resolution

   # Quick rollback if needed
   ./shared/scripts/deploy/rollback.sh production
   
   # Or hotfix
   git checkout -b hotfix/critical-issue
   # Implement fix
   ./shared/scripts/deploy/deploy.sh production
   

Security Issues

1. Assess vulnerability

   • Determine severity and impact
   • Check for exploitation

2. Response

   • Implement temporary mitigation
   • Develop permanent fix
   • Deploy security patch

3. Post-mortem

   • Document the incident
   • Update security procedures
   • Improve monitoring

📈 Performance Optimization

Frontend Performance

Bundle Optimization

# Analyze bundle size
cd frontend
pnpm build --analyze

# Code splitting
const ParkDetail = () => import('./views/ParkDetail.vue')

Image Optimization

• Use WebP format for images
• Implement lazy loading
• Optimize image sizes

Backend Performance

Database Optimization

# Use select_related for foreign keys
parks = Park.objects.select_related('operator')

# Use prefetch_related for many-to-many
parks = Park.objects.prefetch_related('rides')

Caching Strategy

• Cache frequently accessed data
• Use Redis for session storage
• Implement database query caching

🔒 Security Best Practices

Code Security

• Regular dependency updates
• Security scanning with tools like Snyk
• Code review security checklist
• Input validation and sanitization

Infrastructure Security

• HTTPS everywhere
• Secure headers implementation
• Regular security audits
• Access control and authentication

📋 Checklist

Before Committing Code

• Tests pass
• Code follows style guidelines
• No linting errors
• Documentation updated
• Commit message follows convention

Before Creating Pull Request

• Feature branch up to date with main
• All tests pass
• Code review checklist completed
• Documentation updated
• No merge conflicts

Before Merging to Main

• CI/CD pipeline passes
• Code review approved
• Tests pass in CI environment
• No critical security issues

This workflow ensures consistent, high-quality development across the ThrillWiki monorepo while maintaining excellent collaboration and deployment practices.