Bumps a Python package dependency across Home Assistant Core integrations, regenerates core requirement files, runs verification tests and prek lint, and prepares a pull request with proper release/compare links.
Bumps a Python package dependency across Home Assistant Core integrations, regenerates core requirement files, runs verification tests and prek lint, and prepares a pull request with proper release/compare links.
Bump Python Package Dependency in Home Assistant Core
Follow these systematic steps to successfully bump a python package requirement in the repository, regenerate necessary derivative files, verify the integration, and raise a pull request.
Gotchas & Non-Obvious Constraints
PR Template Integrity: Follow Home Assistant's Pull Request template (.github/PULL_REQUEST_TEMPLATE.md) exactly as written, including any instructions inside the template itself. Preserve all sections, comments, and unchecked checkboxes unless the template explicitly says otherwise; the only allowed removal is the Breaking change section when the template instructs you to remove it if not applicable.
GitHub Tag Volatility: Release tags on GitHub are highly inconsistent (e.g., v1.2.3 vs 1.2.3 vs release-1.2.3). Always use the automated resolver resolve_dependency.py to check HEAD status for correct tags before hardcoding comparison URLs.
Step-by-Step Workflow Checklist
Phase A: Research and Plan
1. Identify Targets: Note the requested target package and target version to bump.
2. Discover Codebase References: Search the codebase to find all manifest.json and requirements files referencing the package.
3. Resolve Version/Tag Details: Run the integrated validation helper script to resolve version details, GitHub repo, release tag format, and formatted PR links:
uv run --no-sync python3 ./.claude/skills/bump-dependency/scripts/resolve_dependency.py <package> <old_version> [--new-version <new_version>]
4. Plan-Validate-Execute (Draft Plan): Before modifying any files, write a brief, structured plan outlining the integrations to change, old version, new version, and the resolved comparison link. Show this draft plan to the user.
Phase B: Execute and Validate (Local Changes)
5. Check Uncommitted Changes: Check for any uncommitted changes in the repository. If they exist, ask the user whether to stash, commit, or discard them before proceeding.
6. Git Branch Setup: Create a clean branch starting from the latest upstream/dev:
git fetch upstream dev
git checkout -b bump-<package>-to-<version> upstream/dev
7. Apply Bump to manifests: Update the version constraint string in all identified manifest.json files (e.g., change "package==1.0.0" to "package==1.1.0").
8. Regenerate Core Requirements: Run the requirements generator to update all derivative requirements and constraint files:
uv run --no-sync python3 -m script.gen_requirements_all
9. Validate Requirements: Check git diff to ensure that only the targeted manifest.json files and requirements_all.txt (and potentially standard constraints) were modified. No unrelated files must be affected.
10. Local Venv Verification: Install the exact targeted package version directly inside the virtual environment:
uv pip install "<package>==<version>"
Phase C: Validation Loop (Tests & Lint)
11. Run Integration Tests: Execute the pytest suite for all integrations that consume the bumped package:
uv run --no-sync pytest tests/components/<integration_name>
Validation Loop: If tests fail, analyze the error, apply appropriate fixes, and re-run pytest until all tests pass cleanly.
12. Run prek Lint Checks: Run the local prek hooks on modified files:
uv run --no-sync prek run
Validation Loop: If prek checks report any formatting or linting violations, fix them and repeat uv run --no-sync prek run until it passes completely without errors.
Phase D: User Confirmation & PR Creation
13. Commit Changes: Commit the clean changes:
git add <modified_files>
git commit -m "Bump <package> to <version>"
14. Push Branch: Push the local branch to your origin remote:
git push origin bump-<package>-to-<version>
15. PR Description Preparation: Generate the pull request body from .github/PULL_REQUEST_TEMPLATE.md:
Proposed change: Describe the package, old version, new version, target/source branches, and insert the resolved PyPI, changelog, and comparison diff links.
Type of change: Check only 1 box in this section, and mark the Dependency upgrade checkbox as checked: [x] Dependency upgrade.
Breaking change: You may remove the "Breaking change" section entirely from the template.
Validation checklists: Mark The code change is tested checkbox as checked: [x] The code change is tested.
Keep remaining template intact: Do NOT remove any other commented-out blocks, headers, or unchecked checkboxes in the template.
16. Mandatory Review Presentation: Format the PR proposal using the PR Presentation Template below and display it to the user. Stop and wait for the user to review and explicitly confirm/approve the PR template and draft details before creating the PR.
17. Raise Pull Request: Once the user approves, create the Pull Request using the GitHub CLI:
gh pr create --repo home-assistant/core --base dev --head <username>:bump-<package>-to-<version> --title "Bump <package> to <version>" --body-file <pr_body_file>
