
Package Bump Planner — Safe Upgrade Order
Package Bump Planner
Plan the upgrade before you touch a version. Most failed upgrades are not about one bad package: two bumps went into one commit, a major hid among patches, a >= line pulled a new release by itself, or a package needed a Python newer than the one in use. Package Bump Planner reads your manifest, your lockfile and a list of target versions, and puts the bumps in a safe order.
$ python3 scripts/package_bump_planner.py batches examples/requirements.txt --targets examples/targets_pip.json --deps examples/deps_pip.json --python 3.9
batch 1 layer 0 apply [safe] retry-helper, webkit-lite
batch 2 layer 0 apply [high-risk: major] pytemplate
batch 3 layer 0 apply [high-risk: minor-0x] queue-kit
batch 4 layer 1 apply [safe] datalayer
batch 5 layer 1 HOLD [blocked] fastroute
5 batches
$ python3 scripts/package_bump_planner.py pins examples/requirements.txt --targets examples/targets_pip.json
retry-helper (line 7): not pinned with == (found '>=1.0')
1 pin findings
$ python3 scripts/package_bump_planner.py bounds examples/requirements.txt --targets examples/targets_pip.json --python 3.9
fastroute 0.36.3 -> 0.40.0: needs Python >=3.10 but you run 3.9
1 blocked bumps
What it does:
- Reads
requirements.txt,package.jsonandpackage-lock.json(v1, v2, v3); lockfile versions replace the ranges inpackage.json - Sorts every bump into
patch,minor,minor-0x(a 0.x minor can break),majorordowngrade, and rates the risk - Orders the bumps in layers from the dependency edges, so a package is upgraded after the packages it needs
- Groups the bumps into batches: safe ones together, every major alone, runtime-blocked bumps on
HOLD - Flags
>=and other unpinned requirements, and npm ranges with no lockfile - Checks each target's
pythonornoderequirement against the runtime you give - Text, Markdown or JSON output; exit codes for CI (0 clean, 1 findings, 2 unreadable, 3 invalid input)
Honest limits: it never looks up versions, so the target list comes from you; it does not read changelogs, so the risk is a rule of thumb from the version numbers; for pip projects the order is only as good as the edge file you write.
Python 3.9+ (tested on macOS with Python 3.9.6 and 3.10.4). Standard library only. The tool makes no network calls, needs no credentials and never changes your files; it only reads the files you name.


