mirror of
https://github.com/home-assistant/core.git
synced 2026-06-02 13:44:32 +01:00
Abílio Costa
51 lines
3.2 KiB
Markdown
51 lines
3.2 KiB
Markdown
---
|
|
applyTo: "homeassistant/components/**, tests/components/**"
|
|
excludeAgent: "cloud-agent"
|
|
---
|
|
|
|
<!-- Automatically generated by gen_copilot_instructions.py, do not edit -->
|
|
|
|
|
|
## File Locations
|
|
- **Integration code**: `./homeassistant/components/<integration_domain>/`
|
|
- **Integration tests**: `./tests/components/<integration_domain>/`
|
|
|
|
## General guidelines
|
|
|
|
- When looking for examples, prefer integrations with the platinum or gold quality scale level first.
|
|
- Polling intervals are NOT user-configurable. Never add scan_interval, update_interval, or polling frequency options to config flows or config entries.
|
|
- Do NOT allow users to set config entry names in config flows. Names are automatically generated or can be customized later in UI. Exception: helper integrations may allow custom names.
|
|
- For entity actions and entity services, avoid requesting redundant defensive checks for fields already enforced by Home Assistant validation schemas and entity filters; only request extra guards when values bypass validation or are transformed unsafely.
|
|
- When validation guarantees a key is present, prefer direct dictionary indexing (`data["key"]`) over `.get("key")` so invalid assumptions fail fast.
|
|
- Integrations should be thin wrappers. Protocol parsing, device state machines, or other domain logic belong in a separate PyPI library, not in the integration itself. If unsure, ask before inlining.
|
|
- Integrations should not implement fixes or workarounds for limitations in libraries. Instead, the library should be updated to fix the issue.
|
|
|
|
The following platforms have extra guidelines:
|
|
- **Diagnostics**: [`platform-diagnostics.md`](platform-diagnostics.md) for diagnostic data collection
|
|
- **Repairs**: [`platform-repairs.md`](platform-repairs.md) for user-actionable repair issues
|
|
|
|
## Entity platforms
|
|
|
|
- Ensure `async_added_to_hass()` and `async_will_remove_from_hass()` have symmetrical behavior. For example, if a subscription is created in `async_added_to_hass()`, it should be unsubscribed in `async_will_remove_from_hass()`. Also, if something is torn down in `async_will_remove_from_hass()`, it should be set up in `async_added_to_hass()`.
|
|
|
|
## Integration Quality Scale
|
|
|
|
- When validating the quality scale rules, check them at https://developers.home-assistant.io/docs/core/integration-quality-scale/rules
|
|
- When implementing or reviewing an integration, always consider the quality scale rules, since they promote best practices.
|
|
|
|
Template scale file: `./script/scaffold/templates/integration/integration/quality_scale.yaml`
|
|
|
|
### How Rules Apply
|
|
1. **Check `manifest.json`**: Look for `"quality_scale"` key to determine integration level
|
|
2. **Bronze Rules**: Always required for any integration with quality scale
|
|
3. **Higher Tier Rules**: Only apply if integration targets that tier or higher
|
|
4. **Rule Status**: Check `quality_scale.yaml` in integration folder for:
|
|
- `done`: Rule implemented
|
|
- `exempt`: Rule doesn't apply (with reason in comment)
|
|
- `todo`: Rule needs implementation
|
|
|
|
|
|
## Testing Requirements
|
|
|
|
- Tests should avoid interacting or mocking internal integration details. For more info, see https://developers.home-assistant.io/docs/development_testing/#writing-tests-for-integrations
|