Welcome to HA-Dev-Template Discussions!

[chrisdpurcell]

Welcome to HA-Dev-Template

A complete development environment for creating production-grade Home Assistant custom integrations.

---

Overview

HA-Dev-Template provides the infrastructure and tooling necessary to develop Home Assistant integrations that meet or exceed the Integration Quality Scale standards. This repository serves as a foundation for developers building reliable, maintainable, and well-tested custom components.

What's Included

Development Environment

• Python 3.14.2 with Home Assistant 2026.2.0
• Complete dependency management and virtual environment configuration
• Automated environment verification and validation

Code Quality Infrastructure

• Ruff for linting and code formatting
• mypy for static type checking
• pre-commit hooks for automated quality enforcement
• pytest with Home Assistant-specific testing tools

Reference Implementation

• Fully functional example integration demonstrating best practices
• DataUpdateCoordinator pattern implementation
• Config flow with error handling and validation
• Comprehensive test suite with >80% coverage

Automation & CI/CD

• GitHub Actions workflows for testing and validation
• Automated dependency updates
• Release management automation

Documentation

• Integration Quality Scale compliance checklist
• HACS publishing guide
• Security best practices
• Performance optimization patterns
• Migration strategies

---

Discussion Categories

General

Q&A and Troubleshooting

• Implementation questions and technical guidance
• Debugging assistance for coordinator, config flow, or entity issues
• Architecture and design pattern recommendations
• Testing strategy and pytest configuration

Show and Tell

Community Projects

• Integrations built with this template
• Novel implementation patterns
• Quality Scale achievements (Bronze → Platinum)
• Performance benchmarks and optimization results

Ideas

Template Improvements

• Enhanced example patterns
• Additional documentation
• Tooling enhancements
• CI/CD workflow improvements

Announcements

Project Updates

• New releases and feature additions
• Breaking changes and migration guides
• Best practice updates
• Home Assistant compatibility changes

---

Getting the Most from This Template

Initial Setup

1. Review Documentation: Start with README.md for quick start instructions
2. Verify Environment: Run `python scripts/verify_environment.py` after setup
3. Study the Example: Examine example_integration/ to understand structure
4. Check Quality Standards: Review QUALITY_CHECKLIST.md before development

Development Workflow

1. Plan Architecture: Use DataUpdateCoordinator for polling integrations
2. Implement Config Flow: Never use YAML configuration for new integrations
3. Write Tests First: Target minimum Bronze tier (automated tests required)
4. Follow Type Safety: Use modern Python 3.14 type hints throughout
5. Run Quality Checks: Execute `pre-commit run --all-files` before commits

Best Practices

• Async-First: All I/O operations must be asynchronous
• Error Handling: Properly handle `UpdateFailed` and `ConfigEntryAuthFailed`
• Entity Availability: Implement availability logic using `CoordinatorEntity`
• Unique IDs: Provide stable unique identifiers for all entities
• Documentation: Document why, not just what

---

Community Standards

Asking Questions

When requesting assistance, please include:

• Context: What you're trying to accomplish
• Code: Relevant snippets (use code blocks with syntax highlighting)
• Errors: Complete error messages and tracebacks
• Attempts: What you've already tried
• Environment: Python version, HA version, relevant dependencies

Providing Answers

• Explain the reasoning behind solutions, not just the code
• Reference official documentation where applicable
• Suggest testing strategies to validate solutions
• Consider edge cases and error scenarios

Sharing Work

• Link to public repositories when possible
• Describe challenges encountered and how they were solved
• Share metrics (test coverage, performance improvements, quality tier achieved)
• Highlight innovative patterns or approaches

---

Important Distinctions

This Is a Template Repository

HA-Dev-Template is development infrastructure, not an end-user integration. Issues specific to integrations built from this template should be reported in those integration's repositories. Use this discussion space for:

• ✅ Template features, bugs, or improvements

• ✅ General HA integration development questions

• ✅ Design patterns and best practices

• ✅ Testing and quality assurance strategies

• ❌ Issues with integrations you've built (use your repo)

• ❌ General Home Assistant support (use HA community)

• ❌ Feature requests for specific devices (use manufacturer repos)

For template bugs or feature requests, open an issue rather than a discussion.

---

Resources

Official Documentation

• Home Assistant Developer Docs
• Integration Quality Scale
• Creating Your First Integration

Template Documentation

• CLAUDE.md - Development patterns and AI assistant guidance
• REFERENCE_GUIDE.md - Comprehensive technical reference
• CONTRIBUTING.md - Contribution guidelines

Implementation Guides

• Quality Checklist
• HACS Integration
• Security Best Practices
• Performance Optimization

---

Getting Started

New to the template? Introduce yourself:

• What integration are you developing?
• What's your experience level with Home Assistant development?
• What Quality Scale tier are you targeting?
• What aspect of integration development interests or challenges you most?

Experienced developer? Consider:

• Sharing your implementation patterns
• Answering questions from newcomers
• Proposing template improvements
• Contributing documentation enhancements

---

Let's build reliable, maintainable, and production-grade Home Assistant integrations together.

For template-specific issues, open an issue. For development questions and community discussion, you're in the right place.