A modernization roadmap is a sequence of risk gates
A roadmap is not a promise to rewrite all of legacy code; it is a way to manage uncertainty. Each milestone has a concrete fragment, owner, evidence, exit criteria, and a decision: proceed, narrow, hold, or rollback.
The sequence is determined not by architectural elegance, but by the combination of business criticality, change risk, dependencies, and the ability to observe the result.
Milestone structure
| Field | Content |
|---|---|
| Target fragment | one flow, boundary, or module |
| Reason | which risk or operational pain is reduced |
| Owner | who confirms behavior and makes the decision |
| Dependencies | seams, data, flags, teams, or checks |
| Evidence gate | what must be checked before moving on |
| Exit criteria | when the slice is complete or ready for the next one |
| Rollback/hold | what to do on regression or insufficient evidence |
Example sequence without invented results
- Discovery: confirm current behavior, module boundaries, and critical flows.
- Baseline: record the observable contract, invariants, and available checks.
- Seam: choose one verifiable separation point and describe dependency direction.
- Slice: perform one incremental refactoring or strangler fragment.
- Gate: compare behavior, side effects, checks, and the risk map.
- Expand or hold: decide based on evidence rather than the calendar plan.
- Retire: remove the legacy fragment only after separate exit criteria and a rollback window.
Modernization roadmap anti-patterns
- a big-bang rewrite with a completion date but no intermediate evidence gates;
- a roadmap as a list of every desired refactor without business priority;
- one milestone changing architecture, dependencies, and behavior at the same time;
- an owner listed formally but without authority to confirm the contract;
- success measured by the number of moved lines rather than reduced risk;
- legacy removal scheduled before coverage of the new path and rollback are proven.
Roadmap review before the next step
Before moving to the next milestone, check that the previous result can be explained through concrete evidence: which inputs passed, which outputs were observed, what changed in the risk map, and which unknowns remain. If the answer depends on an assumption, the milestone is not ready to expand.
It is normal for a modernization roadmap to contain hold or deferred work. A deferred fragment with a clear reason is safer than removing legacy code without sufficient control.
Canonical lesson source · JavaRush
Open JavaRush material