mirror of
https://github.com/pacnpal/thrillwiki_django_no_react.git
synced 2025-12-20 07:11:08 -05:00
feat: major API restructure and Vue.js frontend integration
- Centralize API endpoints in dedicated api app with v1 versioning - Remove individual API modules from parks and rides apps - Add event tracking system with analytics functionality - Integrate Vue.js frontend with Tailwind CSS v4 and TypeScript - Add comprehensive database migrations for event tracking - Implement user authentication and social provider setup - Add API schema documentation and serializers - Configure development environment with shared scripts - Update project structure for monorepo with frontend/backend separation
This commit is contained in:
pacnpal
649
shared/docs/development/workflow.md
Normal file
649
shared/docs/development/workflow.md
Normal file
@@ -0,0 +1,649 @@
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
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**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
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)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# Deploy to development
|
||||
./shared/scripts/deploy/deploy.sh dev
|
||||
|
||||
# Check deployment status
|
||||
./shared/scripts/deploy/check-status.sh dev
|
||||
```
|
||||
|
||||
#### Manual Deployment
|
||||
1. **Build frontend**
|
||||
```bash
|
||||
cd frontend
|
||||
pnpm build
|
||||
```
|
||||
|
||||
2. **Run backend migrations**
|
||||
```bash
|
||||
cd backend
|
||||
uv run manage.py migrate
|
||||
```
|
||||
|
||||
3. **Collect static files**
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
git checkout -b release/v1.2.3
|
||||
```
|
||||
|
||||
2. **Update version numbers**
|
||||
- Update `package.json`
|
||||
- Update `pyproject.toml`
|
||||
- Tag the release
|
||||
|
||||
3. **Final testing**
|
||||
```bash
|
||||
# Run full test suite
|
||||
pnpm run test
|
||||
|
||||
# Performance testing
|
||||
./shared/scripts/test/performance-test.sh
|
||||
```
|
||||
|
||||
#### Production Deployment
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```python
|
||||
# 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.
|
||||
Reference in New Issue
Block a user