Fix ZHA blocking minor version downgrades#171319
Conversation
Per the config flow migration docs, minor version bumps must be backwards-compatible: a downgrade within the same major version should still load. The previous guard compared the tuple (version, minor_version) against the handler, which incorrectly turned any minor downgrade into a MIGRATION_ERROR. Compare only the major version so minor downgrades load as the contract requires.
Covers both sides of the contract: - minor-version downgrade (MINOR_VERSION + 1) loads as LOADED - major-version downgrade (VERSION + 1) fails with MIGRATION_ERROR
home-assistant
Bot
added
bugfix
cla-signed
has-tests
integration: zha
small-pr
|
Hey there @dmulcahey, @Adminiuga, @puddly, mind taking a look at this pull request as it has been labeled with an integration ( Code owner commandsCode owners of
|
There was a problem hiding this comment.
Pull request overview
This PR updates ZHA config entry migration so downgrades from future minor versions no longer block integration setup, while still blocking future major versions.
Changes:
- Loosens the ZHA migration guard to reject only future major config entry versions.
- Adds tests covering allowed minor-version downgrades and blocked major-version downgrades.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
homeassistant/components/zha/__init__.py |
Updates migration downgrade guard to compare only major config entry versions. |
tests/components/zha/test_init.py |
Adds regression coverage for minor and major downgrade behavior. |
puddly
left a comment
puddly
left a comment
There was a problem hiding this comment.
Thanks for catching this!
I wonder: would it be better to be more explicit with blocking downgrades? I feel like returning False is easily overlooked but raise BlockDowngrade is obvious.
- Parametrize the two cases into one test, matching the existing migration test style in the file. - Assert version/minor_version are preserved in both paths to confirm the guard returns before mutating any state. - Use MINOR_VERSION + delta instead of a magic literal in the major-downgrade case.
|
As the PR introducing the guard was included in 2026.5.3, I've also added this PR to the milestone now. |
Normally users will downgrade to the latest patch of a release. So it's theoretically but we cannot do nothing about it |
Proposed change
This fixes a small issue where ZHA blocked setup of the integration if the user tried to downgrade from a potential future HA version with a higher
MINOR_VERSIONto HA Core 2026.5.3. Addresses a review comment in: #171164 (comment).This is done by loosening the guard preventing downgrades (causing a
MIGRATION_ERRORstate ifFalseis returned). Now, only major version downgrades are blocked, as is correct per the documentation, and how most other integrations handle this.Coverage for that line is also added with two tests.
Type of change
Additional information
Checklist
ruff format homeassistant tests)If user exposed functionality or configuration variables are added/changed:
If the code communicates with devices, web services, or third-party tools:
Updated and included derived files by running:
python3 -m script.hassfest.requirements_all.txt.Updated by running
python3 -m script.gen_requirements_all.To help with the load of incoming pull requests: