Dependency Upgrades: Blind Bump vs Staged Migration (Prompts)
Rivermouth Public Library runs its lending system on Django 3.2, and that version stopped receiving security fixes months ago. The system holds 340,000 active loan records, keeps renewals running for fourteen branches, and cannot afford a weekend of downtime during exam season. So when the municipal IT team finally approved the work, the temptation was a one-line request: upgrade Django 3.2 to 5 and hand back the requirements file.
That request produced a plausible-looking dependency list that would have broken the lending API on the first deploy. This article compares the blind bump the team almost shipped with the staged migration prompt that replaced it, explains why the staged version plans for rollback before it plans an upgrade, and gives you an upgrade brief you can reuse for any aging dependency.
What a Blind Version Bump Breaks
Major framework versions change more than version numbers. Django 3.2 to 5 crosses a settings deprecation, a new default primary key type, changes to URL routing helpers, and a long list of third-party packages that have not caught up. A model asked to “upgrade” will happily bump the pinned versions and declare success, because nothing in a requirements file tells it which packages your code actually calls.
- The symptom: an upgraded requirements file, a clean install, and a runtime crash on the first request.
- The cause: the request named a target version but not the constraints that make it safe, such as tests, rollback, and compatibility.
- The fix: stage the upgrade, isolate each breaking change, and define the rollback before writing a single line.
The One-Line Upgrade Request
This is what the junior developer sent first, after a long day.
Upgrade our Django project from 3.2 to 5. Give me the new requirements file.What came back: a tidy list with every Django line pinned to 5.0 and the usual companions bumped to their latest releases. It looked correct. It also silently upgraded the REST framework to a version that dropped a serializer argument the lending API used, renamed a middleware path, and ignored the fact that the library’s own authentication package still required Django 4.
The file installed without error. The first call to the renewal endpoint returned a 500, and the failure pointed at a serializer rather than at the upgrade, so the developer spent an afternoon chasing the wrong thing.
The Staged Migration Prompt
The rewrite does not ask for a finished file. It asks for a plan whose first deliverable is the ability to undo everything.
You are planning a Django upgrade for a municipal public library lending system.
Current version: Django 3.2. Target: Django 5.0. The codebase serves a REST API
used by fourteen branches and a web dashboard.
Do not write code yet. Produce a staged migration plan:
1. Inventory: list the categories of change to check, including settings
deprecations, the default primary key change, URL routing helpers, and
third-party packages that pin a Django version.
2. Order the work into at least four stages, smallest breaking change first.
3. For each stage, state the test that proves the stage is safe, and the exact
rollback step if it fails.
4. Flag every dependency that must be upgraded before Django itself, and why.
5. Give a single go or no-go checkpoint before the final stage.
Assume no production downtime during business hours is acceptable. Prefer many
small reversible steps over one large change.What came back: a five-stage plan. It put the authentication package upgrade first because Django 5 would not load with the pinned version, isolated the primary key change into its own stage behind a test on the loan and fine tables, and required a rollback to a tagged database snapshot before the routing stage. The junior developer shipped it over two weeks, one stage every few days, with zero overnight incidents.
Why Staging Survives Contact With Production
A staged plan works because it converts one unknowable risk into several knowable ones. Nobody can predict how a framework major version will interact with a live lending database, but you can absolutely predict whether one isolated change passes its test and whether you can undo it.
The rollback requirement is the part that changes behaviour. When every stage must name its own undo, the plan naturally avoids the changes that cannot be reversed safely, such as an unversioned primary key migration run straight on production. The go or no-go checkpoint then gives the team an explicit place to stop rather than a vague hope that the last step works. For the same reason, keep the mechanical refactors that follow an upgrade separate from the upgrade itself, the split we describe in our legacy refactor workflow.
Writing Your Own Upgrade Brief
Reuse this brief for any dependency you are nervous about. The numbered order is not decoration; each block removes a different failure mode.
You are planning an upgrade of [package] from [current version] to [target].
The system is [what it does] and serves [who depends on it].
Do not write code yet. Produce a staged plan:
1. Inventory the categories of breaking change to check for this upgrade.
2. Order the work into at least four stages, smallest breaking change first.
3. For each stage: the test that proves it is safe, and the exact rollback step.
4. Flag every dependency that must move before [package] itself, and why.
5. Add one go or no-go checkpoint before the final stage.
Constraints: [downtime rules], and prefer many small reversible steps.
Output the plan as a numbered list, then one line of open questions.Two habits make the brief earn its keep. First, always request the inventory before the plan, because the list of change categories is where the model is most useful and where a blind bump skips ahead. Second, ask for the open questions line; the unanswerable items it names are the ones to raise with your team before the first stage. A database migration this sensitive is its own discipline, and the general shape is covered in our database migration prompt.
Save the brief as a template. The next time Rivermouth has to move a package, the variables are the version numbers and the downtime rule, and the reversibility discipline comes along for free.
A Pre-Flight Check Before You Start
Before you accept a migration plan, put it through these questions. Each one maps to a real failure that a blind bump would have shipped.
- Which dependency must move before the main one, and what breaks if it does not?
- For every stage, what is the exact command or step that undoes it?
- Is any step irreversible without a database snapshot, and is that snapshot tested?
- What test proves each stage safe, and does that test actually touch the affected table?
- Where is the single go or no-go checkpoint, and who calls it?
The team at Rivermouth added one rule of its own: no stage ships on a Friday. It sounds superstitious, but it keeps a fresh breaking change from meeting a weekend support rotation with nobody available to roll back. The plan is only as good as the discipline around it.
If a plan arrives with stages but no rollback steps, treat it as a draft, not a deliverable. Ask for the undo for the first stage specifically, and read the answer carefully. A model that can name the rollback is reasoning about your system; one that cannot is only shuffling version numbers, which is exactly the blind bump you were trying to escape.
Sources & Notes
The staged-migration pattern and the brief are our own framing, reviewed on 2026-10-12. Rivermouth Public Library, the 340,000 active loan records, and the fourteen branches are illustrative examples. Django version specifics such as the default primary key change and the middleware path rename are described at a high level and may differ by release, so confirm details against the official release notes for your exact versions before acting. Never run a schema migration straight on production without a tested rollback. Language models change between versions, so re-check any prompt that depends on a specific package name or version number.
