When to run it
An end-of-life date on a runtime or framework (for example Java 11 to 21, Spring Boot 2 to 3, Python 3.8 to 3.12, React class components to hooks) with a long tail of services nobody wants to own.
Framework upgrades,one reviewable PR at a time.
Upgrading a framework across dozens of services
The playbook in one paragraph
A major framework or runtime version is going end-of-life and it touches every service. Ana plans the migration, upgrades each service in its own branch, fixes what breaks, and hands your team small, tested pull requests instead of one terrifying diff.
Works with
- GitHub, GitLab or Bitbucket
- Maven / Gradle / npm / pip / Poetry
- Existing CI (GitHub Actions, GitLab CI, Jenkins, Azure DevOps)
- Jira or Linear for tracking
What Ana needs from you
- Target versions and any pinned constraints
- Service list (or let Ana discover it from the repos)
- Definition of done: build green, tests green, no new deprecation warnings
How Ana runs it
Step by step.
6 steps from trigger to done - each one visible to your team as it happens.
- 01
Map the blast radius
Ana reads every repository, builds the dependency graph and lists which services use deprecated APIs, transitive libraries that block the upgrade, and shared modules that must move first.
- 02
Order the migration
Shared libraries go first, leaf services last. Ana proposes a sequence and a ticket per service so the work can be reviewed in parallel by the owning teams.
- 03
Upgrade and repair
For each service Ana bumps versions, applies the API changes, replaces removed calls, and fixes compile and test failures - reading the code it changes rather than pattern-replacing it.
- 04
Prove it still works
Ana runs the existing test suite in CI, adds tests where coverage around changed code is thin, and compares behaviour before and after for the endpoints it touched.
- 05
Open small PRs
One pull request per service, each with a summary of what changed and why, the risky spots called out, and links to the upstream migration notes it followed.
- 06
Track the long tail
Ana keeps a running board of upgraded, in review and blocked services, and comes back to blocked ones when the shared dependency they wait on lands.
Who approves what
Approval gates
- Merge to main
- Owning team reviewer
- Shared library release
- Platform / library owners
- Production deploy
- Your existing release process - Ana does not bypass it
What you get
Deliverables
- 01A pull request per service with passing CI
- 02New or extended tests around changed code
- 03Migration plan and dependency order
- 04A status board of the whole upgrade
What usually goes wrong
And how Ana handles it.
Risk
Hidden runtime behaviour changes
Ana flags APIs whose semantics changed between versions and adds targeted tests rather than relying on compilation alone.
Risk
One giant diff nobody can review
Work is split per service and per concern so every PR stays reviewable in one sitting.
Risk
Flaky tests masking real breakage
Ana re-runs failures, separates known-flaky tests from new failures, and reports both.
FAQ
Common questions.
No. Ana opens pull requests; merging follows your branch protection and review rules.
Keep going
Related playbooks.
Software
Extracting a service from a legacy monolith
A module inside the monolith needs to become its own service. Ana documents what the module really does, defines the contract, builds the service behind a strangler route, and proves parity before any traffic moves.
Read the playbook →Software
Burning down a stale bug backlog
Every team has a backlog of real but low-priority bugs that never win a sprint. Ana triages them, reproduces the ones that are still real, fixes them with tests, and closes the rest with evidence.
Read the playbook →Security
Turning a pentest report into merged fixes
A penetration test lands as a PDF with dozens of findings. Ana parses it, confirms which findings are reachable in your code and cloud, writes the fixes with regression tests, and hands the auditor evidence for every closure.
Read the playbook →See it in your stack
Run this playbook on your systems.
Thirty minutes, your repositories and cloud, one real instance of this job.