This directory contains comprehensive implementation guides for developing Home Assistant custom integrations using this template.
| Guide | Purpose | Audience |
|---|---|---|
| Quality Checklist | Track progress toward Bronze→Platinum tiers | All developers |
| HACS Integration | Publish integration to HACS | Distribution planning |
| Security Best Practices | Secure credential and API handling | All developers |
| Migration Guide | Config entry version migrations | Maintenance |
| Performance | Optimization and efficiency tips | Intermediate+ |
| Localization | Multi-language support | I18n implementation |
| Documentation Audit | Automated doc-code alignment tool | Maintainers |
For New Developers:
- Start with ../README.md for quick start
- Review QUALITY_CHECKLIST.md to understand quality tiers
- Read SECURITY_BEST_PRACTICES.md before implementing auth
For Publishing:
- Achieve at least Bronze tier (see QUALITY_CHECKLIST.md)
- Follow HACS_INTEGRATION.md for HACS submission
- Use ../CHANGELOG.md to document releases
For Maintenance:
- Reference MIGRATION_GUIDE.md when changing config entry structure
- Use PERFORMANCE.md to optimize existing integrations
- Implement LOCALIZATION.md for international users
- ../CLAUDE.md - AI assistant instructions and mandatory patterns
- ../REFERENCE_GUIDE.md - Comprehensive technical reference
- ../resources/ha-dev-environment-requirements.md - Environment setup
- ../.github/AUTOMATION_GUIDE.md - CI/CD and automation
# 1. Initial setup
source venv/bin/activate
python scripts/verify_environment.py
# 2. Track progress
# Open docs/QUALITY_CHECKLIST.md and check off items as you implement them
# 3. Implement securely
# Reference docs/SECURITY_BEST_PRACTICES.md while coding
# 4. Optimize
# Use docs/PERFORMANCE.md to ensure efficient coordinator usage
# 5. Localize (optional)
# Follow docs/LOCALIZATION.md to add translations
# 6. Migrate (when needed)
# Use docs/MIGRATION_GUIDE.md for config entry updates
# 7. Publish
# Follow docs/HACS_INTEGRATION.md for HACS submissionThis template helps you achieve Home Assistant's Integration Quality Scale tiers:
-
Bronze (Minimum) - Start here
- Config flow UI setup
- Automated tests
- Basic coding standards
- See QUALITY_CHECKLIST.md for complete list
-
Silver (Reliability) - Recommended minimum
- Error handling
- Entity availability
- Troubleshooting docs
- User-friendly config flow
-
Gold (Feature Complete) - Professional quality
- Full async codebase
- ≥90% test coverage
- Complete type annotations
- Efficient data handling
-
Platinum (Excellence) - Core integration quality
- All best practices
- Clear documentation
- Optimal performance
- Active maintenance
Q: Where do I start? A: Read ../README.md first, then open QUALITY_CHECKLIST.md to see what you need to implement.
Q: How do I distribute my integration? A: Follow HACS_INTEGRATION.md after achieving Bronze tier minimum.
Q: My integration is slow. How do I optimize it? A: Review PERFORMANCE.md for coordinator and polling optimization strategies.
Q: How do I handle credentials securely? A: Read SECURITY_BEST_PRACTICES.md for authentication patterns.
Q: I need to change my config entry structure. How? A: Use MIGRATION_GUIDE.md to implement async_migrate_entry().
Q: How do I add translations? A: Follow LOCALIZATION.md for strings.json and translations/ setup.
Found an issue or want to improve these guides?
- File an issue at the repository's issue tracker
- Submit a pull request with improvements
- Include examples and code snippets where applicable
- Follow the existing structure and tone
- Example Integration: ../custom_components/example_integration/
- Test Suite: ../tests/
- Skills & Agents: ../resources/
- GitHub Workflows: ../.github/workflows/
Need help? Join the Home Assistant Community or check the HA Developer Docs.