ad-ha/kidschores-ha 0.5.0b on GitHub

What's Changed

refactor!: Complete v0.5.0 Architecture overhaul & new features by @ccpk1 in #224

⚠️ Beta Notice

This is a beta release and you may encounter unexpected issues. We appreciate your help testing!

Good news: One of the key improvements in v0.5.0 is automatic backup creation before any migration runs. If you experience problems after upgrading, recovery is straightforward:

Go to Settings → Devices & Services → KidsChores → Configure
Select General Options
Choose Recovery / Backup Management
Select the pre-migration backup file (tagged with pre-migration)
Confirm restore

Running the recovery has fixed a few issues with initial migrations, but there is a fix in place that should resolve that now. That said please report any issues so we can address them before the stable release.

BREAKING CHANGES:

Storage Migration: Entity data moved from config_entry to .storage/kidschores_data (Schema v42).
Entity Visibility: Non-essential "extra" sensors are now disabled by default (opt-in via Integration General Options).
Reward Claims: Previously any claim for a reward would be cleared at midnight, so if a parent missed it, the kid would need to request again. Now all reward claims remain in claim status until approved or rejected.
Dashboard Compatibility: v0.5.0 is NOT compatible with legacy dashboard versions. Updated dashboard can be download from: https://github.com/ccpk1/kidschores-ha-dashboard/releases/tag/KCD_v0.5.0_beta1 . Instructions in that release have been updated, be sure to read closely.

🏛️ Architecture, Data Structure & Integrity

Storage-Only Mode: Decoupled entity data from HA config entries. This architecture resolves previous data loss issues and enables unlimited entity scaling.
Standardized Data Model: Reorganized internal data structures into a clean, unified schema for points, chores, and rewards to facilitate future extensibility.
Device-Centric Grouping: Utilized Home Assistant's native Device Registry to automatically group entities into distinct "Kid" devices or a unified "System" device, providing a structured and intuitive entity organization.
Entity Clarity: Added a purpose attribute to all entities, providing immediate, human-readable context on each entity's specific function to simplify identification and debugging.
Future-Ready Statistics: Implemented consistent statistical structures across all domains (points, chores, rewards), laying the groundwork for advanced frontend visualization and user-facing analytics. Many are already available in the kids _points and _chores entities.
Native Backups: Integration data is included in standard Home Assistant backups via the storage directory.
Performance: Achieved 8x faster integration reload times by bypassing legacy config processing.

⚡ Chore Engine & Scheduling Overhaul

Multi-Kid "Independent" Fix: Resolves usability issue where chores assigned to multiple kids were somewhat treated as shared. The system now strictly tracks per-kid due dates, ensuring one kid's overdue reset does not affect others.
"Shared First" Competition Mode: New completion criteria mode where multiple kids are offered a chore, but only the first to claim it receives points (blocks subsequent claims). This is good for things that either kid can do, but only needs done once.
Approval Reset Timing: Implemented 5 granular reset modes (e.g., at_midnight_once, upon_completion) to control exactly when approvals reset and how often chores can be claimed within the approval window.
Approval Reset Claim Handling: Previously any open claims would be cleared at midnight when the approval cycle reset if the parent had not approved. This meant the kid would not get credit for that chore. This is still the default option, but now you have additional options such as automatically approve open claims at reset and prevent reset until claim is approved or rejected.
Overdue Handling: Configurable logic to either never go overdue, go overdue until complete, or go overdue until the approval windows ends and reset.
Auto-Approve: New "trusted" option allows specific chores to bypass parent approval steps automatically.
Calendar Visibility: Per-chore toggle to hide specific tasks (like daily routines) from the main calendar feed.

🛡️ Backup & Troubleshooting

Automatic Safety: Implemented automatic backups before destructive operations with ISO 8601-compliant data/time naming.
Manual Backups: Take manual backups of data file at any time.
Diagnostics: Added standard Home Assistant "Download Diagnostics" support, including a full JSON data copy for simplified issue reporting.
Easy Restore: Built-in restoration capabilities to restore from an existing file or even accept JSON copy/paste directly from data or diagnostic files.

🏅 Advanced Gamification (Badges)

Cumulative System: New tiered badge engine (e.g., Bronze/Silver/Gold) tracking total lifetime earned points. This only tracks points earned, so the kid is not penalized for using those points for rewards. This is the only badge type that can award a multiplier like 1.2x where each time you earn 10 points from a chore you will be awarded 12 as long as you keep the badge active. Parents can choose to add maintenance cycles where kids need to earn a certain number of points in the maintenance period or their multiplier drops down to the next lower badge.
Periodic Badges: Custom time-frame logic with advanced criteria (e.g., "80% chore completion daily over 10 days"). These badges can award points, rewards, or bonuses, but they can also be used to apply penalties, for instance if chores go overdue.
Daily Badges: Performance-based badges that reset every 24 hours.
Special Occasions: Logic for specific date-based awards (e.g., birthdays).

🌍 Localization & Translations

11-Language Support: Fully functional translation system for integration and dashboard elements, powered by Crowdin for automated machine translations and updates. Crowdin provides an open source license to us allowing us to assign translators or add new languagues to the full system with relative ease.
Dual-System Architecture:
- Native: Uses standard HA patterns (en.json) for core integration features like exceptions and config flows.
- Custom: Implemented a translations_custom infrastructure (following native patterns) to handle capabilities not supported by the native integration, specifically for notifications (en_notifications.json) and dashboard UI (en_dashboard.json). Note that language selection for these custom translations can be found in the integration configuration, General Options \ Manage Kids \ kidname \ Language
Master-File Workflow: English files are the exclusive source of truth; all non-English keys are managed via automated Crowdin syncs to the l10n-staging branch, enabling automatic key updates without manual file editing. All language edits and approvals occur in Crowdin

📊 Dashboard & Statistics

Smart Helper: Introduced a dashboard helper sensor to pre-compute critical UI logic, delivering key entity names, pre-sorted lists, and translations directly to the frontend.
- Performance: Significantly optimizes rendering by eliminating hundreds of expensive template lookups on every dashboard reload.
- Sustainability: Replaces the previous unsustainable translation approach with a streamlined, attribute-based delivery system.
- Zero-Dependency: Removes requirement for external "Date Picker" helpers and reduces entity clutter.
Detailed Stats: Implemented comprehensive statistic structures for points, chores, and rewards, all governed by granular retention policies (Daily/Weekly/Monthly/Yearly).

✅ Quality Assurance (Unofficial Silver Standard)

Silver Certification: Codebase updated to meet Home Assistant Silver Quality Scale requirements.
Strict Typing & Logging: 100% type hint coverage and 100% lazy logging (no f-strings) implemented throughout the coordinator.
Standardization: Enforced consistent naming for 1,000+ constants and unified exception handling using translation keys.

📘 Documentation & Development Standards

Standards Definition: Created STANDARDS.md to strictly define naming conventions (1,000+ constants), error handling patterns, and entity hierarchy requirements.
Architectural Blueprint: Created ARCHITECTURE.md to document the storage-only design, schema v42 specifications, and data flow diagrams.
Quality Maintenance: Added CODE_REVIEW_GUIDE.md and QUALITY_MAINTENANCE_REFERENCE.md to standardize code audits and enforce the "Silver" quality scale.

Effort Summary

Comprehensive refactor of 50+ files to eliminate hundreds of lines of duplication, enforcing strict standardization, unified error handling patterns, and Silver-level code quality across the entire codebase.
173 commits over 10 months.
Validated with 679/679 passing tests (100% active coverage).

Full Changelog: 0.3.1...0.5.0b