Breaking changes to audit before any framework upgrade
Turn release notes into behavioral contracts, evidence, and a rollout plan that includes persisted data and background processes.
Give every relevant change an owner and a test
An upgrade audit should connect a documented change to application behavior. A list of deprecated method names is useful, but it misses failures caused by defaults, serialization, boot order, or deployment overlap. Begin with the official upgrade guide for every crossed major version and the compatibility notes for critical dependencies.
For each relevant item, record the affected entry point, expected behavior, verification method, and rollback limitation. Mark an item inapplicable only with evidence: a code search, a configuration inspection, or a dependency inventory. Do not turn a low-impact label in a vendor guide into a low-risk label for an application that heavily uses that feature.
Write one concrete audit record
This YAML describes a Laravel 10 → 11 schema risk. It is a review template, not executable migration tooling. Replace the illustrative table and column with a real affected migration, then attach the observed schema comparison. The same record shape works for a changed cookie default or response serializer.
change: laravel_11_column_modifier_retention
status: awaiting_verification
example_surface: invoices.amount
risk: a_change_migration_drops_required_column_attributes
evidence_required:
- inventory_of_change_calls
- schema_after_fresh_install
- schema_after_upgrade_from_previous_fixture
acceptance:
- precision_scale_nullability_and_default_match_intent
- old_and_new_app_can_read_the_expanded_schema
rollback_limit: reverting_code_does_not_restore_lost_data
owner_role: database_change_reviewer
Prioritize contracts that cross boundaries
HTTP contracts include status codes, redirect destinations, validation errors, authentication cookies, and response fields. Test a rejected request as well as a successful one. An endpoint that changes from a JSON 401 to an HTML login redirect may break a client even though browser-based login still works.
Persisted contracts include database types, cache keys, session serialization, queued payloads, and object-storage paths. These can outlive the process that wrote them. Build fixtures with the old version and read them using the new one. If rolling deployment is supported, also test the reverse direction for data the new version produces.
Process contracts include boot hooks, dependency lifetimes, environment loading, and signal handling. A web-only test suite cannot prove that a scheduler runs once or that workers reload new code. List those processes explicitly and test them using the deployment arrangement you intend to keep.
Separate installation evidence from behavior evidence
Package-manager diagnostics establish whether declared constraints are satisfiable. They cannot establish that a package behaves correctly with your application. Keep a shortlist of dependencies touching authentication, payments, storage, and database access, and exercise those integrations with test credentials and synthetic records.
Keep the audit narrow enough to finish. For each high-risk change, one focused regression test and one integration rehearsal can be more informative than adding many assertions to unrelated unit tests. Capture the actual runtime and database versions with results so a passing local SQLite run is not mistaken for a production-engine schema test.
Plan failure handling before the release
Choose stop conditions tied to observed behavior: unauthorized access, lost writes, repeatedly failing jobs, or a material increase in error rate. Define who decides to stop and which artifact is restored. Avoid inventing a universal percentage threshold; choose one from the service baseline and the consequence of failure.
Database recovery needs its own procedure and evidence. If a migration removes information, a code rollback cannot recreate it. Prefer an additive transition and delayed cleanup where practical. Close the audit only when each applicable item has evidence or an explicitly accepted limitation, including how long mixed versions are allowed to run.