Dependency upgrade

Renovate and Dependabot open the PR. This skill lands it: a breaking major upgrade is code migration work, and "just bump the version" is how production breaks. The contract: one dependency at a time, changelog before bump, tests after every step, and a bisect when something breaks.

Install the CLI:

pip install bumpmap

1. Plan: which upgrades are even dangerous

bumpmap plan pyproject.toml            # or requirements*.txt; --json for agents

== requirements.txt
  [MAJOR   ] pydantic     1.10.13  -> 2.7.4
            major jump 1.10.13 -> 2.7.4: read the changelog's breaking changes and plan code changes before bumping
  [MINOR   ] requests     2.31.0   -> 2.32.3
            changelog: https://requests.readthedocs.io/en/latest/community/updates/

Risk classes: latest (already current), minor (same major — usually safe, tests still decide), major (breaking changes possible — the real work), unpinned (pin it first, an unpinned dependency can't be planned). Exit 1 on any major — CI-gateable. --from-cache pypi.json replays a saved PyPI lookup offline.

Work in this order: all minor bumps in one commit (tests decide), then major jumps one dependency per commit — a break after a combined commit is unbisectable.

2. Read the changelog like a migration guide, not like news

For a major jump, open the changelog/migration guide and extract the exhaustive list of breaking changes that touch the code. Then grep the codebase for each affected API before bumping:

grep -rn "from pydantic import" --include="*.py" | wc -l     # blast radius first

If the blast radius is a handful of call sites, the migration is a bounded task; if it's 200 files, say so and propose doing it in modules. The changelog's own migration sections (pydantic v2, httpx, pytest 8…) usually include codemod tools — run the official codemod first, fix what it leaves.

3. The loop: bump → run → fix → commit

pip install "pydantic==2.7.4"       # bump the pin too, in the same commit
pytest -q                            # the tests decide
# fix what broke; repeat until green
git commit -m "upgrade pydantic 1.10 -> 2.7 (breaking; migration notes applied)"

• Tests must exist before the bump. If coverage of the affected area is thin, write characterization tests against the old version first — they encode current behavior the migration must preserve (or deliberately change, with a note).
• One break that you can't fix quickly? Bisect it the same way: which test, which API, which changelog entry. A dead end after honest effort is a result: report "blocked by X, Y unchanged" instead of half-reverting.
• Don't mix an upgrade commit with feature work — the revert of an upgrade should be one revert.

4. Verify beyond the tests

• Run the app's real entrypoint once (import errors and plugin loading failures don't show in unit tests).
• Check for deprecated-API warnings from the new version (-W error::DeprecationWarning in pytest) — they're next major's breaking changes, cheaper to fix now.
• If the project has a lockfile, regenerate it in the same commit; a half-updated lock is a broken deploy.
• Re-run bumpmap plan after: the dependency should now read latest, and no new major lines should appear.

5. Report

upgraded: pydantic 1.10.13 → 2.7.4 (major; 14 call sites migrated, official codemod + 3 manual fixes)
verified: 231 tests green; entrypoint boots; deprecation warnings: 0
not touched: flask 2.x→3.x (next; separate commit), requests 2.32.3 (minor, landed with the batch)

Say what was upgraded, what was deliberately left, and what the next follow-up is — an upgrade report with "not touched" lines is a plan, not an excuse.

Scope

Upgrades in projects you own. The skill assumes the project has runnable tests; upgrading a major without any tests is a different conversation — propose writing characterization tests first instead of bumping blind.