This checklist should be used before publishing or distributing a new version of MHA Widget Hub.
A release should be:
- buildable;
- installable;
- testable in Home Assistant;
- documented;
- visually stable;
- safe for existing user storage;
- compatible with the current extension architecture.
Before release:
- remove temporary debug logs;
- remove unused test files;
- remove experimental dead code;
- confirm no local-only paths are committed;
- confirm no
.DS_Storefiles are included; - confirm generated artifacts are intentional;
- confirm documentation links work.
Check for accidental files:
find . -name ".DS_Store"Confirm version-related files are updated if applicable:
package.json
hacs.json
custom_components/*/manifest.json
README.md
CHANGELOG.md
Exact files may vary depending on the current packaging structure.
Run:
npm install
npm run check:syntax
npm test
npm run buildIf any command fails, stop the release.
Confirm tests pass for:
- storage;
- pages;
- placement;
- responsive layout;
- widget factory;
- widget registry/catalog;
- widget previews;
- Home Assistant bindings;
- entity permissions;
- wallpaper storage;
- theme tokens;
- screensaver controller;
- DOM lifecycle.
Open dev.html and verify:
- app loads without raw code flash;
- widgets render;
- widget manager opens;
- live previews render;
- config popup opens;
- settings panel opens;
- dock positions work;
- theme switching works;
- wallpaper controls work if changed;
- resize behavior is stable.
In Home Assistant, verify:
- sidebar panel appears;
- panel opens;
- no blank screen;
- navigating away and back works;
- frontend cache does not show old code;
- real
hassentity states are read; - service calls work for supported widgets;
- config popup lists real entities;
- admin visibility filtering works;
- reload preserves layout/settings.
Test at least one widget from each active family:
- clock;
- button;
- toggle;
- slider;
- toggle-slider;
- weather;
- media.
For each affected widget, verify:
- manager entry;
- preview;
- config flow if any;
- placement;
- render;
- state persistence;
- Home Assistant behavior.
Test:
- OneUI light/dark;
- Material light/dark;
- iOS Liquid light/dark;
- iOS Frosted light/dark.
Check:
- widgets;
- dock;
- status bar;
- settings panel;
- widget manager;
- config popup;
- text contrast;
- borders;
- blur;
- accents.
Test:
- desktop wide;
- desktop narrow;
- tablet;
- mobile;
- orientation changes if possible;
- dock left;
- dock right;
- dock bottom;
- mobile floating buttons.
Watch for:
- horizontal overflow;
- cropped panels;
- dock outside viewport;
- tiny widgets on first load;
- frozen layout during startup.
Before release, verify existing users are not broken.
Test with:
- fresh storage;
- old stored widgets;
- invalid/missing stored values;
- multiple pages;
- custom wallpapers;
- existing theme settings;
- existing dock position;
- admin entity visibility settings.
Confirm migrations/defaults work safely.
Confirm packaged files include everything needed:
custom_components/mha_widget_hub/__init__.py
custom_components/mha_widget_hub/manifest.json
custom_components/mha_widget_hub/brand/*
custom_components/mha_widget_hub/frontend/mha-widget-hub.js
custom_components/mha_widget_hub/frontend/mha-widget-hub-loader.js
custom_components/mha_widget_hub/frontend/mha-admin-loader.js
custom_components/mha_widget_hub/frontend/mha-diagnostics-loader.js
custom_components/mha_widget_hub/frontend/src/*
custom_components/mha_widget_hub/frontend/styles/*
custom_components/mha_widget_hub/frontend/assets/*
Confirm packaged files exclude unnecessary files:
node_modules
.DS_Store
temporary screenshots
local-only scripts
debug output
If using HACS, verify:
- repository structure is valid;
- the GitHub release contains
mha-widget-hub.zipandmha-widget-hub-hacs.zip; hacs.jsonpoints to that ZIP release asset;- install path is correct;
- frontend resources are available;
- integration/panel registration works;
- update path does not require manual cleanup.
Confirm docs are updated when relevant:
README.md
docs/installation.md
docs/user-guide.md
docs/widgets.md
docs/themes.md
docs/theme-tokens.md
docs/preview-system.md
docs/config-flows.md
docs/architecture.md
docs/development.md
docs/testing.md
docs/release-checklist.md
README should stay light.
Advanced details should stay in docs/.
Write a changelog entry with:
- user-visible changes;
- developer changes;
- breaking changes if any;
- migration notes if any;
- known issues if any.
Example format:
## x.y.z
### Added
- ...
### Changed
- ...
### Fixed
- ...
### Internal
- ...
### Known Issues
- ...If there is a breaking change, document:
- what changed;
- who is affected;
- how to migrate;
- whether storage is migrated automatically;
- whether users must clear cache;
- whether Home Assistant restart is required.
Avoid breaking existing stored widgets unless there is a migration.
Before publishing:
- Fresh browser session.
- Open Home Assistant.
- Open MHA from sidebar.
- Add a configurable widget.
- Add a non-configurable widget.
- Change theme.
- Change dock position.
- Reload page.
- Navigate away and back.
- Confirm state persists.
When ready:
git status
git log --oneline -n 5Confirm working tree is clean.
Then tag according to the project versioning strategy.
Example:
git tag v0.x.y
git push origin v0.x.yOnly tag after tests and manual checks are complete.
After release/install/update:
- install through the expected path;
- open MHA in Home Assistant;
- verify version/update is actually loaded;
- test one widget;
- test one theme switch;
- check browser console;
- check Home Assistant logs if integration files changed.
Before release, know how to roll back:
- previous git tag;
- previous HACS release;
- previous frontend JS file;
- user storage compatibility.
If a release changes storage format, rollback may be more complicated.
Document this in the changelog if relevant.
Do not release only because the build passes.
A safe MHA release needs:
automated checks
+
manual UI checks
+
Home Assistant checks
+
documentation updates
The project is UI-heavy, so visual/manual validation is part of the release process.