homeassistant==2026.3.4 requires Python>=3.14.2. The lint workflow was
specifying Python 3.13, and uv venv was ignoring actions/setup-python and
picking up the system Python (3.14.0) instead.
Changes:
- lint.yml: python-version 3.13 → 3.14
- bootstrap: uv venv now uses $(which python) to respect
actions/setup-python and local pyenv/asdf setups
Impact: lint workflow no longer fails with Python version unsatisfiable
dependency error when installing homeassistant.
Release workflow now automatically deletes tags when version number doesn't
match commit types (e.g., PATCH bump when MINOR needed for features).
Changes:
- New step 'Delete inappropriate version tag' runs after version_check
- Automatically deletes tag and exits with error if version inappropriate
- All subsequent steps conditional on successful version validation
- Improved warning message: removed confusing 'X.Y.Z' placeholder
- Added notice: 'This tag will be automatically deleted in the next step'
- Removed redundant 'Version Check Summary' step
Impact: Users get immediate, clear feedback when pushing wrong version tags.
Workflow fails fast with actionable error message instead of creating release
with embedded warning. No manual tag deletion needed.
Major restructuring of the scripts/ directory with consistent output
formatting, improved organization, and stricter error handling.
Breaking Changes:
- Updated development environment to Home Assistant 2025.7+
- Removed Python 3.12 compatibility (HA 2025.7+ requires Python 3.13)
- Updated all HA core requirements from 2025.7 requirement files
- Added new dependencies: python-multipart, uv (for faster package management)
- Updated GitHub Actions workflows to use Python 3.13
Changes:
- Created centralized output library (scripts/.lib/output.sh)
- Unified color codes and Unicode symbols
- Consistent formatting functions (log_header, log_success, log_error, etc.)
- Support for embedded formatting codes (${BOLD}, ${GREEN}, etc.)
- Reorganized into logical subdirectories:
- scripts/setup/ - Setup and maintenance scripts
- bootstrap: Install/update dependencies (used in CI/CD)
- setup: Full DevContainer setup (pyright, copilot, HACS)
- reset: Reset config/ directory to fresh state (NEW)
- sync-hacs: Sync HACS integrations
- scripts/release/ - Release management scripts
- prepare: Version bump and tagging
- suggest-version: Semantic version suggestion
- generate-notes: Release notes generation
- check-if-released: Check release status
- hassfest: Local integration validation
- Updated all scripts with:
- set -euo pipefail for stricter error handling
- Consistent SCRIPT_DIR pattern for reliable sourcing
- Professional output with colors and emojis
- Unified styling across all 17 scripts
- Removed redundant scripts:
- scripts/update (was just wrapper around bootstrap)
- scripts/json_schemas/ (moved to schemas/json/)
- Enhanced clean script:
- Improved artifact cleanup
- Better handling of accidental package installations
- Hints for reset and deep clean options
- New reset script features:
- Standard mode: Keep configuration.yaml
- Full mode (--full): Reset configuration.yaml from git
- Automatic re-setup after reset
- Updated documentation:
- AGENTS.md: Updated script references and workflow guidance
- docs/development/: Updated all references to new script structure
Impact: Development environment now requires Python 3.13 and Home Assistant
2025.7+. Developers get consistent, professional script output with better
error handling and logical organization. Single source of truth for styling
makes future updates trivial.
HACS automatically displays the version number before release titles,
causing duplication when version tags are included in the title.
Changes:
- scripts/generate-release-notes: All backends now generate intelligent
titles without version prefix (git-cliff, manual, and copilot)
- scripts/generate-release-notes: Added smart title generation based on
commit analysis (feat/fix counts) for git-cliff and manual backends
- scripts/generate-release-notes: Unified section headers to use ### (H3)
instead of ## (H2) for consistency across all backends
- scripts/generate-release-notes: Auto-update feature now uses extracted
title without prepending version tag
- .github/workflows/release.yml: Extract title directly from generated
release notes (first line with "# ") instead of manual construction
- .github/workflows/release.yml: Removed redundant "Generate release title"
step
Before (HACS): v0.9.0: v0.9.0 - New Features
After (HACS): v0.9.0: Multi-Home Support & Diagnostic Sensors
Impact: Release titles in HACS are now cleaner with single version display
and more descriptive titles generated intelligently from commit content.
All three backends (copilot, git-cliff, manual) produce consistent output
with H1 title followed by H3 sections.
Major improvements to release note generation system:
**AI Model Optimization:**
- Switch from Claude Sonnet 4.5 to Haiku 4.5 (67% cheaper, 50% faster)
- Cost reduced from 1.0 to 0.33 Premium requests per generation
- Generation time reduced from ~30s to ~15s
- Quality maintained through improved prompt engineering
**Improved Prompt Structure:**
- Restructured prompt: instructions first, commit data last
- Added explicit user-feature prioritization rules (sensors > config > developer tools)
- Integrated file change statistics with each commit
- Added file path guidance (custom_components/ = HIGH, scripts/ = LOW)
- Added 3-step decision process with walkthrough example
- Added explicit output constraints to prevent meta-commentary
**Auto-Update Feature:**
- Consolidated improve-release-notes functionality into generate-release-notes
- Automatic detection of existing GitHub releases
- Interactive prompt to update both title and body
- Shows comparison: current title vs. new AI-generated title
**File Statistics Integration:**
- Added --stat --compact-summary to git log
- Shows which files changed in each commit with line counts
- Helps AI quantitatively assess change importance (100+ lines = significant)
- Enables better prioritization of user-facing features
**Testing Results:**
- Generated title: "Price Volatility Analysis & Configuration" (user-focused!)
- Successfully prioritizes user features over developer/CI changes
- No more generic "New Features & Bug Fixes" titles
- Thematic titles that capture main release highlights
Impact: Release note generation is now faster, cheaper, and produces
higher-quality user-focused titles. Single consolidated script handles
both generation and updating existing releases.
Release titles now automatically reflect the type of changes:
- 'vX.Y.Z - New Features & Bug Fixes' (both present)
- 'vX.Y.Z - New Features' (only features)
- 'vX.Y.Z - Bug Fixes' (only fixes)
- 'vX.Y.Z' (fallback for other changes)
Determined by analyzing commit messages between previous tag and current tag.
Impact: Release titles are more descriptive and immediately show what
changed, making it easier for users to understand the release at a glance.
Added concurrency groups with cancel-in-progress to validate.yml, lint.yml,
and auto-tag.yml workflows.
This ensures that when multiple commits are pushed quickly:
- Only the latest validation/lint run continues
- Older runs are automatically cancelled
- Saves CI minutes and provides faster feedback
Release workflow intentionally excluded (each tag is unique).
Impact: More efficient CI usage, faster feedback on rapid commits.
Release workflow now trusts that validate.yml and lint.yml have already
run on the main branch commit before tag creation. This prevents duplicate
workflow executions.
Workflow execution flow:
1. Push to main → validate.yml + lint.yml run (quality gate)
2. prepare-release or auto-tag creates version tag
3. release.yml runs (generates release notes, no validation)
This ensures:
- Every main commit is validated/linted before tag creation
- No duplicate workflow runs (validate/lint run once per commit)
- Release workflow is faster (no redundant checks)
- Simple, predictable workflow chain
Impact: Release process is more efficient and workflows don't run twice.
Added mandatory validation steps to release workflow:
- Job 1: validate (hassfest + HACS) - runs before release
- Job 2: lint (Ruff check + format) - runs before release
- Job 3: sync-manifest - only runs if validation passes
- Job 4: release-notes - only runs if all previous jobs pass
This ensures no release is created if code doesn't pass validation.
Fixed generate-release-notes script to suppress colored output in CI:
- Added log_info() wrapper that sends output to stderr in CI
- Keeps release notes clean (only markdown, no ANSI codes)
- Local execution still shows colored output for better UX
Impact: Release workflow now fails fast if validation fails. Release
notes are clean without shell output artifacts.
Updated copilot-instructions.md with comprehensive documentation for
new release workflows and validation requirements.
Added sections:
- Selector validation rules for hassfest compliance
- Pattern requirement: [a-z0-9-_]+ (lowercase only)
- Common pitfalls with SelectOptionDict and translation_key
- Validation examples (correct vs incorrect)
- Legacy/Backwards compatibility guidelines
- When to add migration code vs breaking changes
- check-if-released script usage
- Rule: Only migrate for released changes
- Prefer documentation over complexity
- Semantic versioning workflow
- Pre-1.0 vs Post-1.0 versioning rules
- suggest-version script usage and output
- prepare-release integration
- Version check in CI/CD
- Release notes generation
- Updated with auto-sync and version check features
- Backend comparison (AI vs git-cliff vs manual)
- Complete workflow examples
Impact: AI assistant and developers have clear guidance on hassfest
requirements, legacy migration decisions, and the complete release
automation workflow. Reduces errors and maintains consistency across
sessions.
Implemented automatic manifest.json synchronization and semantic
versioning validation in the release workflow.
Auto-Sync Manifest (sync-manifest job):
- Extracts version from Git tag (v*.*.*)
- Compares with manifest.json version
- Auto-updates manifest.json if mismatch detected
- Commits changes back to main branch
- Sets outputs (updated, version) for downstream jobs
- Prevents HACS version mismatches and conflicts with auto-tag.yml
Version Check Warning System (version_check step):
- Analyzes commits between tags for breaking changes, features, fixes
- Applies semantic versioning rules (pre-1.0 and post-1.0)
- Detects inappropriate version bumps:
- Features with only PATCH bump → suggests MINOR
- Breaking changes with only MINOR bump → suggests MAJOR (post-1.0)
- Breaking changes with only PATCH bump → suggests MINOR (pre-1.0)
- Shows warnings in GitHub Step Summary (prominent)
- Appends warnings to release notes body
- Provides fix instructions but doesn't fail workflow
- Updates final summary with version check status
Workflow changes:
- release-notes job now depends on sync-manifest
- Checks out main branch to get updated manifest if synced
- Summary shows manifest sync status and version check result
Impact: Prevents manual version tag issues, maintains manifest
consistency, and warns about semantic versioning violations without
blocking releases. Fully transparent workflow with clear guidance.
Created professional documentation structure:
**User Documentation (docs/user/):**
- README.md: Documentation hub with quick start guide
- Placeholder files for future content migration:
* installation.md, configuration.md, sensors.md
* services.md, automation-examples.md, troubleshooting.md
**Developer Documentation (docs/development/):**
- README.md: Comprehensive contributor guide with AI section
- setup.md: DevContainer and environment setup
- architecture.md: Code structure overview
- testing.md: Testing guidelines
- coding-guidelines.md: Style guide and critical patterns
- release-management.md: Complete release workflow documentation
**AI Development Disclosure:**
- README.md: "🤖 Development Note" section before license
* Honest disclosure about extensive AI assistance
* Quality assurance measures mentioned
* Invitation for bug reports with positive tone
- docs/development/README.md: Detailed AI section
* What AI handles (patterns, generation, refactoring)
* Benefits (rapid development, consistency)
* Limitations (edge cases, complex patterns)
* Quality assurance process
- CONTRIBUTING.md: Brief AI note with practical tip
**Updated:**
- README.md: Simplified to landing page with documentation links
- CONTRIBUTING.md: Modernized with new docs structure
- copilot-instructions.md: Added documentation organization section
Impact: Clear separation of user vs. developer documentation following
open-source best practices. Transparent about AI-assisted development
approach without being defensive. Scalable structure for future growth.
