Adding upgrade rule mechanism in ZAP for SDKs #1589
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Collaborator
- Users can now include an upgrade rules json file in the zcl.json file which has a list of all the upgrade rules that may be needed when a user updates an existing app from one version of the GSDK to another.
- The upgrade rules json file lists a set of upgrade rules scripts with their priority as can be seen in upgrade-rules.json file. The scripts are run in order of priority with lower number signifying higher priority
- The upgrade rules return an object including a message and status which helps determine if an upgrade rules was actually executed or not. These results can be output into a yaml file if required for post analysis on which upgrade rules ran on a certain .zap file once the GSDK was updated.
- Github: ZAP#1020
There was a problem hiding this comment.
Pull Request Overview
This PR introduces an upgrade rule mechanism for ZAP, allowing users to include an upgrade rules JSON file that lists upgrade rule scripts with associated priorities. The upgrade rules are read from each package, sorted by priority, and then executed during file import, with their messages gathered for optional output.
- Added new return value in the test script for endpoint deletion.
- Integrated upgrade rule processing in the main process startup and import/export modules.
- Improved directory creation logic when writing out conversion results.
Reviewed Changes
Copilot reviewed 3 out of 5 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| test/resource/test-script-2.js | Returns an object with a message and status after endpoint deletion. |
| src-electron/main-process/startup.js | Introduces processing of upgrade rules from package JSONs with sorting by priority. |
| src-electron/importexport/import.js | Adds handling and execution of post-import upgrade scripts and associated logging. |
Files not reviewed (2)
- zcl-builtin/silabs/upgrade-rules.json: Language not supported
- zcl-builtin/silabs/zcl-zigbee.json: Language not supported
Comments suppressed due to low confidence (2)
test/resource/test-script-2.js:22
- [nitpick] Consider using a predefined constant or enum for status values instead of magic strings to maintain consistency across similar functions.
return { message: 'Endpoint Deleted', status: 'automatic' } // Status can be 'nothing', 'automatic', 'user_verification', 'impossible'.
src-electron/main-process/startup.js:331
- Validate that 'upgradeRuleScripts' exists and is an array before attempting to sort it to avoid potential runtime errors if the JSON structure doesn't match expectations.
upgradeRulesData.upgradeRuleScripts.sort((a, b) => a.priority - b.priority)
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
155244c to
6d81f9c
Compare
ethanzhouyc
reviewed
May 9, 2025
ethanzhouyc
reviewed
May 9, 2025
brdandu
commented
May 9, 2025
| } | ||
| ``` | ||
|
|
||
| **category**: Determines that these upgrade rules need to run for matter. |
There was a problem hiding this comment.
Yes if more than 2 zcl json files are not passed then users could pass a any zcl json with upgrade rules in it and they may get executed.
ethanzhouyc
approved these changes
May 9, 2025
ethanzhouyc
reviewed
May 9, 2025
There was a problem hiding this comment.
Pull Request Overview
This PR adds a new upgrade rule mechanism for SDKs by enabling users to specify an upgrade rules JSON file in the zcl.json file. Key changes include:
- Extending the test suite to cover upgrade rule behaviors for both Zigbee and Matter devices. 8000
- Modifying post-import processing and database queries (including a new query module for upgrade rules) to support upgrade rule scripts.
- Updating documentation and the README to cover the new upgrade workflow.
Reviewed Changes
Copilot reviewed 15 out of 19 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| test/startup.test.js | Added tests for upgrade rules with new file import and generation tests. |
| test/resource/* | Added new upgrade rule scripts for Zigbee, Matter, and generic attribute updates. |
| src-electron/util/post-import.js & post-import-api.js | Updated to pass additional context for upgrade rules and to use async functions. |
| src-electron/main-process/startup.js & importexport/import.js | Modified to load and execute upgrade rule scripts during import and upgrade processes. |
| src-electron/db/query-upgrade.js | Introduced a new module to support queries related to upgrade rules. |
| docs/* & README.md | Documentation updates for the new upgrade mechanism. |
Files not reviewed (4)
- zcl-builtin/matter/upgrade-rules-matter.json: Language not supported
- zcl-builtin/matter/zcl-matter.json: Language not supported
- zcl-builtin/silabs/upgrade-rules-zigbee.json: Language not supported
- zcl-builtin/silabs/zcl-zigbee.json: Language not supported
Comments suppressed due to low confidence (1)
test/startup.test.js:44
- Typo in comment: 'testiing' should be 'testing'.
// Save the original file content before tests. Used for uc upgrade testiing
tecimovic
approved these changes
May 9, 2025
Codecov ReportAttention: Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## master #1589 +/- ##
==========================================
+ Coverage 66.93% 67.10% +0.17%
==========================================
Files 197 199 +2
Lines 21827 22306 +479
Branches 4817 4936 +119
==========================================
+ Hits 14609 14968 +359
- Misses 7218 7338 +120 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
daf2900 to
ef1b045
Compare
- Users can now include an upgrade rules json file in the zcl.json file which has a list of all the upgrade rules that may be needed when a user updates an existing app from one version of the GSDK to another. - The upgrade rules json file lists a set of upgrade rules scripts with their priority as can be seen in upgrade-rules.json file. The scripts are run in order of priority with lower number signifying higher priority - The upgrade rules return an object including a message and status which helps determine if an upgrade rules was actually executed or not. These results can be output into a yaml file if required for post analysis on which upgrade rules ran on a certain .zap file once the GSDK was updated. - Adding unit tests to update cluster revision attribute of all clusters - Handling the multi protocol use case and adding unit tests that make sure that only the appropriate endpoints are updated when upgrade rules json files from both zigbee and matter exist - Adding unit tests for matter only .zap file - Adding documentation on how to add upgrade rules to your SDK - Adding the update keys available to the context in postLoad - Add unit tests to check the order in which the upgrade rules were run - Github: ZAP#1020
ef1b045 to
3b4ecf0
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.