A major framework upgrade should pass six gates in order: a green baseline, a clean warning run, unit and integration tests, a security and dependency check, a performance comparison, and a staged rollout. Each gate has an exit criterion written down before you start, so passing is a fact, not a feeling.
The gates
| Gate | Question it answers | Exit criterion |
|---|---|---|
| 1. Baseline | Was it healthy before? | Full suite green on the old version, flaky tests fixed or quarantined |
| 2. Warnings | What will break next? | No new deprecation warnings from your own code |
| 3. Functional | Does it still behave? | Unit and integration tests pass, plus new tests for known risk areas |
| 4. Security | Did we make it worse? | No new known vulnerabilities, dependency diff reviewed |
| 5. Performance | Did it get slower? | Latency and memory within an agreed margin on a representative load |
| 6. Rollout | Does it hold in production? | Canary healthy for an agreed period, rollback tested |
Write the exit criteria into the pull request template for upgrade work so that reviewers check against the same list.
Gate by gate
Baseline. Without a green starting point, you cannot tell which failures your upgrade caused. Fix or quarantine flaky tests first and record the count.
Warnings. Turn on deprecation output in the runtime you use and compare before and after. New warnings point at code that will fail on the next major.
Functional. Add tests where the framework's behavior changed: routing, serialization, session handling, form parsing, template escaping. If a changelog says a default changed, write a test that asserts the behavior you want, then see which version passes.
Security. Compare dependency lists before and after, and scan both. Check authentication, session and cookie settings, CORS and header defaults, since defaults are what upgrades most often move. Run your static and dependency scans in CI as a required check.
Performance. Run the same load test on both versions in the same environment. Compare p50 and p99 latency, memory and startup time. Agree the allowed margin before looking at the numbers.
Rollout. Release to a small share of traffic, watch error rate and latency, then widen in steps. Have the rollback written, rehearsed and fast.
Automating the gates
Gates two to four belong in CI so they run on every push to the upgrade branch. Gates five and six can be a manual or scheduled step, with a recorded result. The point is that anyone can see which gate the upgrade has reached.
Try it yourself
Click through it at your own pace, or open it full screen. Look at how a pull request is blocked or allowed based on policy checks.
Quick check
Do I need all six gates for a minor upgrade?
Usually the first four are enough, with a lighter rollout. Scale the gates to the risk.
Who signs off on the exit criteria?
The service owner, with a security reviewer for services that handle untrusted input.
Safeguard policies and gates can block a pull request on dependency findings, which supports gate four. Try the free scan at gold.safeguard.sh/scan.
Last reviewed: 19 October 2026.
