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.
Expanded the documentation to include a comprehensive update process for maintaining consistency between code and documentation. Added sections on automatic inconsistency detection, documentation update proposals, and guidelines for testing changes and git workflow.
Impact: Ensures accurate documentation and streamlined workflows for future development sessions.
