Move a whole repository onto a new library version

Break a library upgrade into safe, reviewable pull requests so your team actually ships the migration instead of postponing it.

For anyone sitting on an upgrade they keep postponing · 9 steps · 7 min

How it works today.

You read the changelog for the new major version and count forty breaking changes. You grep the codebase and find two hundred files importing the old API. You sketch a plan to rename every call site, update the config schema, and rewrite the error handlers, then realize it will take a week of focused work and block everyone else's branches.

So you leave it. The old version still works. Six months later you are three patch releases behind on security fixes that only ship on the new major. The diff has grown to two hundred and fifty files. You still do not have a free week.

Before you start.

All of it has to be true, or step one fails in a way that is annoying to debug.

Write access to a repository with CI that runs tests on every pull request.
An agent runtime that can read your repo, write code, run your test suite, and open pull requests (like Devin, Factory, Sweep, or Cursor Composer with GitHub integration).
The library's changelog or migration guide, so you can list the breaking changes in order of blast radius.

The steps.

List every breaking change and estimate the file count each one touches
Open the changelog or migration guide. For each breaking change, grep your codebase to count affected files. Sort the list by file count, smallest first. You want to land the ten-file changes before the eighty-file changes so you learn where the agent struggles on small batches.
02
Pick the smallest breaking change and ask the agent to fix it in a single pull request
Give the agent the changelog entry, the list of affected files, and instructions to open one PR. If the change touches fewer than fifteen files, let it run. If it touches more, split the file list in half and do two PRs. Watch the test output; if the agent does not run tests before opening the PR, you need to add that to your prompt.
Paste this
```
Read the migration guide section on [specific breaking change]. Find every file in this repository that imports [old API]. Update each file to use [new API] according to the guide. Run the full test suite. If tests pass, open a pull request with the title 'Migrate [old API] to [new API]' and include the test output in the description. If tests fail, fix the failures and run tests again before opening the PR.
```
Review the first pull request for patterns you need to correct
Do not merge yet. Check whether the agent updated import statements, config files, and test mocks consistently. Check whether it preserved comments and formatting. If it made the same mistake in five places, add a rule to the next prompt. If it skipped a file type, add that type explicitly.

Refine the prompt and send the agent after the next breaking change

Copy your original prompt. Add one sentence for each pattern you found: 'Preserve all existing comments,' 'Update both .ts and .test.ts files,' 'Do not remove error handling blocks.' Run the agent on the next breaking change from your sorted list. If this PR is cleaner, you have a template. If not, refine again before moving to larger changes.

Paste this

Read the migration guide section on [next breaking change]. Find every file in this repository that imports [old API]. Update each file to use [new API] according to the guide. Preserve all existing comments and formatting. Update both source files and test files. Do not remove error handling blocks. Run the full test suite. If tests pass, open a pull request with the title 'Migrate [old API] to [new API]' and include the test output in the description. If tests fail, fix the failures and run tests again before opening the PR.

Merge the first two PRs and check for integration issues
Merge after your team reviews them. Pull main and run the full suite locally, including any integration tests that do not run in CI. If something breaks when two migrations combine, you found a dependency between breaking changes. Note it so you batch those changes together in future PRs.
Send the agent after the remaining small and medium changes in parallel
For every breaking change that touches fewer than thirty files, give the agent your refined prompt and let it open a PR. If your agent supports multiple tasks, queue them all. If not, run them in series. You will have five to ten pull requests open at once. This is fine; each one is small enough to review in ten minutes.
Manually split the largest breaking change into logical boundaries
Find the breaking change that touches the most files. Split it by directory, by module, or by feature area—whatever makes semantic sense in your codebase. Write down the file list for each split. Give the agent one split at a time with your refined prompt. Do not let it touch a hundred files in one PR; your team will not review it carefully.
Set up an eval to catch regressions in the upgraded code
Before you merge the last batch, write a test suite or eval that calls your library's new API in the ways your application actually uses it. Run it against the upgraded code. If you skip this, you will find the regressions in production. If your agent has an observability integration, log every API call during the eval so you can trace failures back to the migration PR.
Merge the remaining PRs and delete the old version from your lockfile
Merge in the order you opened them, smallest to largest. After the last PR lands, remove the old library version from package.json or requirements.txt and commit that separately. Run CI one more time. You are done.

What you keep.

Automating the typing does not move the accountability. These stay with a person.

Deciding which breaking changes to batch together when they share files or logic, because the agent does not understand your domain boundaries.
Reviewing every pull request for correctness, not just test passage, because the agent will make tests pass by deleting assertions if you let it.
Writing the final eval suite that proves the new version works in your actual use cases, because the agent does not know which library features you depend on in production.
Merging the pull requests in an order that keeps main shippable, because the agent does not track cross-PR dependencies.