thrillwiki_django_no_react/docs/MIGRATION_GUIDE.md

Dependency Update Migration Guide

This guide covers the migration to updated dependencies including critical security patches.

For Developers

Local Development Setup

1. Update Python to 3.13+

   python --version  # Should be 3.13+
   

2. Install UV (if not already installed)

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Update Dependencies

   cd backend
   uv sync --frozen  # Use locked versions
   

4. Run Tests

   uv run manage.py test
   

Security Patches Applied

Critical (CVSS 9.0+)

• CVE-2025-64459 (Django) - SQL injection vulnerability
  • Fixed in: Django 5.2.8+
  • Previous version: 5.0.x

High Severity

• CVE-2024-21520 (DRF) - XSS in break_long_headers filter
  • Fixed in: djangorestframework 3.15.2+
  • Previous version: 3.14.x

Medium Severity

• CVE-2024-28219 (Pillow) - Buffer overflow
  • Fixed in: Pillow 10.4.0+
  • Previous version: 10.2.0

Breaking Changes

Python Version

• Minimum: 3.13+ (previously 3.11+)
• Update your local Python installation before proceeding

django-allauth (0.60 → 65.3)

Major version jump. Review your configuration:

# Check your SOCIALACCOUNT_PROVIDERS settings
# Some provider configurations may have changed

sentry-sdk (1.x → 2.x)

If using Sentry, review the SDK v2 migration guide:

• https://docs.sentry.io/platforms/python/migration/

Removed Packages

These packages were removed (not used in codebase):

• channels, channels-redis, daphne
• django-simple-history (using django-pghistory)
• django-oauth-toolkit (using dj-rest-auth)
• django-webpack-loader
• reactivated

Dependency Groups

Dependencies are now organized into groups:

# Production only
uv sync

# Development (includes dev tools)
uv sync --group dev

# Testing
uv sync --group test

# Profiling (optional)
uv sync --group profiling

Troubleshooting

Issue: uv sync fails with dependency conflicts

Solution: Delete uv.lock and regenerate:

rm uv.lock
uv lock
uv sync

Issue: Tests fail after update

Solution:

1. Check for deprecated API usage in test files
2. Review django-allauth changes for auth tests
3. Run uv run manage.py check for specific warnings

Issue: Import errors for removed packages

Solution: Search for and remove any imports of:

• channels
• simple_history
• oauth2_provider
• webpack_loader
• reactivated

Issue: ModuleNotFoundError: cryptography

Solution: This is now included. Run:

uv sync

CI/CD Changes

The CI/CD pipeline now uses UV:

- name: Install Dependencies
  working-directory: backend
  run: uv sync --frozen

Generating requirements.txt

For tools that need requirements.txt:

cd backend
./scripts/generate_requirements.sh

This creates:

• requirements.txt - Production
• requirements-dev.txt - Development
• requirements-test.txt - Testing

Lock File

The project now uses uv.lock for reproducible builds:

# Use locked versions (recommended for CI/deployment)
uv sync --frozen

# Update lock file
uv lock --upgrade

Rollback Procedure

If you need to rollback:

git checkout HEAD~1 backend/pyproject.toml uv.lock
uv sync --frozen