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.
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.
