Long-term approach for addressing upgrade and migration error reports

Upgrades should remain predictable and as stable as possible. When errors are reported, the goal is to diagnose and remediate the underlying data or migration issues rather than altering the upgrade workflow itself. The following practices outline a sustainable process for triaging, fixing, and preventing upgrade-related regressions.

1. Intake and triage

• Reproduce with the same migration state: capture the exact application version, migration history, and feature flags. Re-run the failing migration in an isolated environment (e.g., a fresh database restore or disposable container) to avoid conflating issues with local changes.
• Classify failures: distinguish between migration logic errors (data assumptions, ordering), missing application code (imports, models), and data quality problems (invalid or unexpected values). Avoid assuming the upgrade process itself is at fault unless multiple unrelated migrations are failing.
• Collect structured diagnostics: ensure migration runs log the migration name, app label, and error traceback. Store these logs alongside anonymized sample payloads or database excerpts when possible.