thrillwiki_django_no_react/memory-bank/decisions/history-tracking-migration.md

History Tracking Migration

Context

The project is transitioning from django-simple-history to django-pghistory for model history tracking.

Implementation Details

Base Implementation (history_tracking/models.py)

• Both old and new implementations maintained during transition:
  • HistoricalModel - Legacy base class using django-simple-history
  • TrackedModel - New base class using django-pghistory
• Custom DiffMixin for comparing historical records
• Maintained HistoricalSlug for backward compatibility

Transition Strategy

1. Maintain Backward Compatibility

   • Keep both HistoricalModel and TrackedModel during transition
   • Update models one at a time to use TrackedModel
   • Ensure no breaking changes during migration

2. Model Updates

   • Designer (Completed)

     • Migrated to TrackedModel
     • Updated get_by_slug to use pghistory queries
     • Removed SimpleHistoryAdmin dependency

   • Pending Model Updates

     • Companies (Company, Manufacturer)
     • Parks (Park, ParkArea)
     • Rides (Ride, RollerCoasterStats)
     • Location models

Migration Process

1. For Each Model:

   • Switch base class from HistoricalModel to TrackedModel
   • Update admin.py to remove SimpleHistoryAdmin
   • Create and apply migrations
   • Test history tracking functionality
   • Update any history-related queries

2. Testing Steps

   • Create test objects
   • Make changes
   • Verify history records
   • Check diff functionality
   • Validate historical slug lookup

3. Admin Integration

   • Remove SimpleHistoryAdmin
   • Use standard ModelAdmin
   • Keep existing list displays and search fields

Benefits

• Native PostgreSQL trigger-based tracking
• More efficient storage and querying
• Better performance characteristics
• Context tracking capabilities

Rollback Plan

Since both implementations are maintained:

1. Revert model inheritance to HistoricalModel
2. Restore SimpleHistoryAdmin
3. Keep existing migrations

Next Steps

1. Create migrations for Designer model
2. Update remaining models in this order: a. Companies app b. Parks app c. Rides app d. Location app
3. Test historical functionality
4. Once all models are migrated:
   • Remove HistoricalModel class
   • Remove django-simple-history dependency
   • Update documentation

Technical Notes

• Uses pghistory's default tracking configuration
• Maintains compatibility with existing code patterns
• Custom diff functionality preserved
• Historical slug tracking unchanged
• Both tracking systems can coexist during migration

Completion Criteria

1. All models migrated to TrackedModel
2. All functionality tested and working
3. No dependencies on django-simple-history
4. Documentation updated to reflect new implementation
5. All migrations applied successfully