Major Version Upgrade

Treat a major upgrade as a controlled migration, not as a version-number edit.

The objective is not merely to make the build green. The objective is to preserve accepted behavior, deliberately adopt intended breaking changes, expose unavoidable incompatibilities, and leave evidence that the new stack component is safe to use in the environments that matter.

Combine this skill with software-engineering and the relevant language, framework, database, security, testing, observability, or operations guidance.

Safety invariants

• Know the exact transition. Record the current version, target version, why the upgrade is needed, supported environments, and any compatibility or rollback obligations.
• Read every breaking boundary crossed. When skipping majors, inspect authoritative release notes and migration guides for every intervening major. Do not reason only from the target version.
• Baseline before changing. Establish what currently builds, tests, starts, integrates, and fails before the upgrade. If the baseline is already red, record the known failures so they cannot be misattributed.
• Treat defaults as API. Configuration defaults, security posture, serialization, timeouts, retries, resource limits, generated output, wire formats, and persistence semantics can break behavior even when source code compiles.
• Treat transitive changes as part of the upgrade. Lockfile, dependency graph, runtime/toolchain requirements, plugins, generated code, and indirect packages are part of the migration surface.
• Do not make green by weakening proof. Do not delete useful tests, loosen assertions, suppress errors, disable checks, or replace real behavior with mocks merely to accommodate the new version.
• Keep unrelated upgrades out. Adjacent upgrades are allowed when the target requires them; make those forced changes explicit. Do not opportunistically modernize the rest of the stack.
• Do not risk irreversible state casually. Destructive or one-way data/schema/format migration requires a tested recovery, restore, or explicitly accepted no-rollback plan before non-disposable execution.
• A code revert is not always a rollback. New persisted data, emitted messages, protocol output, cache entries, or generated artifacts may make an old version unable to resume safely.