Phase 5 step-by-step
Run a staff-level Android migration.
Outcome: a migration package for XML to Compose, monolith to modules, RxJava to coroutines, or a networking platform replacement.
1pilot feature
3adopter teams
0blocked releases
Pick one migration and define why
Choose a migration with measurable payoff. Example: XML to Compose for high-change screens.
Checkpoint: if you cannot name the payoff, do not start the migration.
Audit current state
Current-state audit: - 84 XML screens - 12 screens changed every month - 5 duplicated custom widgets - No shared accessibility checklist - Average PR review time: 2.8 days - Known risk: mixed theme behavior across old screens
You have numbers, not opinions, for why the migration matters.
Define target state
Target state: - New screens are Compose-first. - Shared components live in :core:design. - Legacy XML remains supported for stable low-change screens. - Migration happens by product area. - Feature flags protect high-risk screen swaps.
Write the ADR
ADR: Compose-first new feature screens Decision: New feature screens use Compose. Existing XML migrates by risk and change frequency. Rejected option: Big-bang rewrite. Reason rejected: high regression risk and no product delivery during rewrite. Consequences: mixed stack for 6-12 months; training required; design system must support Compose.
Plan the pilot
Pick one low-risk but real screen. Avoid both throwaway examples and mission-critical checkout flows.
| Pilot candidate | Saved businesses screen |
|---|---|
| Why | Real usage, moderate UI complexity, reversible route. |
| Rollback | Route flag returns users to XML screen. |
Create adoption material
- Before/after example PR.
- Component usage guide.
- Migration checklist.
- Known gotchas.
- Office-hours schedule.
- Exception process.
Define metrics and thresholds
| Metric | Threshold | Owner |
|---|---|---|
| Crash-free sessions | No regression vs baseline | Feature team |
| PR review time | Improve by 20% | Staff owner |
| Adoption | 3 teams by quarter end | Platform lead |
| Accessibility | No critical findings | Feature owner |
Run post-migration review
Post-migration review: - What improved? - What regressed? - Which docs were missing? - Which API caused misuse? - Should the migration continue, pause, or change sequence? - What decision should be recorded for the next team?
Staff-level risks
Mandate without enablementTeams resist migrations when examples, docs, and support are missing.
Big-bang rewriteUsually maximizes regression risk and pauses product delivery.
No exception policyWithout exceptions, teams either block or bypass the platform.
Metrics without ownersDashboards are useless without thresholds and response owners.
Completion gate
- Current-state audit is evidence-based.
- ADR explains rejected alternatives.
- Pilot can roll back safely.
- Adoption plan supports other teams.
- Post-migration review decides continue, pause, or adjust.