From commcare-tech
Upgrade a Python or JS dependency safely. Given a library name, finds the latest safe version, reviews the changelog, assesses impact based on how the library is used in the repo, performs the upgrade, and creates a PR with the changelog and assessment. Use this whenever someone asks to upgrade, bump, or update a package/library/dependency.
npx claudepluginhub dimagi/dimagi-claude-workflows --plugin commcare-techThis skill uses the workspace's default tool permissions.
Upgrade a dependency to the latest safe version with a well-documented PR. The goal is to make dependency upgrades low-risk and easy to review — the PR should give reviewers everything they need to feel confident merging.
Scans for outdated npm, pip, Cargo, Go, Ruby packages, runs CVE audits, summarizes breaking changes via Gemini, and opens PRs grouped by risk. Use for dependency updates and security checks.
Plans safe incremental upgrades of project dependencies with risk assessment priority matrix migration guides test strategies and rollback plans. Use for dependency update workflows.
Plans and executes safe incremental upgrades of project dependencies with risk assessment, migration guides, test strategies, rollback plans, and timelines.
Share bugs, ideas, or general feedback.
Upgrade a dependency to the latest safe version with a well-documented PR. The goal is to make dependency upgrades low-risk and easy to review — the PR should give reviewers everything they need to feel confident merging.
$ARGUMENTS — The library/package name. Examples:
/dependency-upgrade pillow/dependency-upgrade django-celery-results/dependency-upgrade markdown-itDetermine whether this is a Python or JS dependency by searching for it in the repo's dependency files:
Python — search requirements/*.txt, requirements.txt, setup.py, setup.cfg, pyproject.toml
JS — search package.json, package-lock.json, yarn.lock
If the library appears in both ecosystems, ask the user which one they mean. If it doesn't appear anywhere, tell the user — the library might not be a direct dependency, or might be spelled differently.
Record the current pinned version.
Fetch version and release date info from the PyPI JSON API:
curl -s https://pypi.org/pypi/<package>/json
From the response:
info.version is the latest releasereleases is a dict keyed by version string, each containing a list of file objects with upload_time_iso_8601npm view <package> versions --json
npm view <package> time --json
The time object maps version strings to ISO date strings.
The point of these rules is to avoid being an early adopter of a release that might have undiscovered issues — we'd rather let the broader community shake out problems first.
Skip X.0.0 major releases. A brand-new major version (e.g., 3.0.0) often has rough edges, breaking changes that aren't fully documented, and ecosystem incompatibilities. Wait for at least X.0.1 or X.1.0 before considering it. If the only available upgrade is an X.0.0, tell the user and suggest waiting.
Skip releases less than 7 days old — except for patch releases (X.Y.Z where only Z changed from the current version). Patch releases are typically bug/security fixes and are safe to adopt immediately. For minor and major releases, a week gives the community time to surface issues.
Pick the best candidate. Walk backwards from the latest version until you find one that passes both rules above. This is the target version.
If no version passes the safety rules, explain why and ask the user if they want to proceed anyway.
Find the changelog between the current version and the target version. Check these sources in order:
project_urls (PyPI) or repository/homepage (npm) to find the GitHub repo.gh api repos/<owner>/<repo>/releases — look for releases tagged between the current and target versions.CHANGELOG.md, CHANGES.md, CHANGES.rst, HISTORY.md, NEWS.md, or similar. Also check a docs/ directory.Summarize the notable changes between the current and target versions — breaking changes, deprecations, new features, and security fixes. Don't paste the full changelog verbatim. Link to the upstream changelog or GitHub Releases page so reviewers can dig deeper if they want.
If no changelog is found, note this — it's still worth proceeding, but flag it in the PR.
Search the codebase to understand how the library is used. This is the most important step for reviewer confidence — the assessment should answer "could this upgrade break anything?"
Find all imports and usages. For Python, search for import <package> and from <package>. For JS, search for require('<package>') and import ... from '<package>'. Count the number of files and note the main usage patterns.
Cross-reference with the changelog. Look for breaking changes, deprecations, or API changes in the changelog that touch functionality the repo actually uses. This is where the value is — not just listing what changed, but whether those changes affect this codebase.
Write a short assessment (3-5 sentences). Cover:
If the risk is high, flag it to the user before proceeding. They may want to handle it manually.
Create a branch: dependency-upgrade/<package>-<target_version>
Update the version pin in the appropriate file(s). For Python requirements files, match the existing pin style (e.g., ==, >=, ~=). For package.json, match the existing prefix (^, ~, exact).
Update lock files if they exist:
uv pip compile to regenerate lock files (this is the team's default). If uv.lock or pyproject.toml with [tool.uv] is present, use uv lock instead. Fall back to pip-compile only if there's no sign of uv in the project.npm install or yarn installDon't run tests — leave that to CI. Just make sure the install/compile step succeeded without errors.
Commit the changes and open a PR. The PR description is the main deliverable — it should give reviewers everything they need.
Upgrade <package> from <current> to <target>
Upgrade <package> from <current> to <target>
Structure the PR description like this:
## Summary
Upgrades `<package>` from `<current_version>` to `<target_version>`.
## Risk Assessment
<the 3-5 sentence assessment from Step 4>
## Changelog
<summary of notable changes — breaking changes, deprecations, new features, security fixes>
<link to full upstream changelog or GitHub Releases page>
## Usage in this repo
<summary of how the library is used — number of files, main patterns>
Keep it concise but complete. Reviewers should be able to approve based on the PR description alone without having to go read the upstream changelog themselves.
/compare/v<current>...v<target>) as a fallback so reviewers can see the raw diff.