63 lines
3.8 KiB
Markdown
63 lines
3.8 KiB
Markdown
---
|
|
title: "Checklist for creating a component"
|
|
---
|
|
|
|
A checklist of things to do when you're adding a new component.
|
|
|
|
> Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them!
|
|
|
|
### 0. Common
|
|
|
|
1. Follow our [Style guidelines](development_guidelines.md)
|
|
2. Use existing constants from [`const.py`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/const.py)
|
|
* Only add new constants to `const.py` if they are widely used. Otherwise keep them on components level
|
|
3. Add yourself to [`CODEOWNERS`](https://github.com/home-assistant/home-assistant/blob/dev/CODEOWNERS) so you [automatically get requested to review](https://help.github.com/en/articles/about-code-owners#codeowners-syntax) the code when it changes in the future
|
|
4. Rebase (**do not merge**) to [catch up with latest dev branch](development_catching_up.html)
|
|
|
|
### 1. Requirements
|
|
|
|
1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']`
|
|
2. We no longer want requirements hosted on GitHub. Please upload to PyPi.
|
|
3. Requirements should [only be imported inside functions](creating_component_deps_and_reqs.md). This is necessary because requirements are installed on the fly.
|
|
|
|
### 2. Configuration
|
|
|
|
1. Voluptuous schema present for [configuration validation](development_validation.md)
|
|
2. Default parameters specified in voluptuous schema, not in `setup(…)`
|
|
3. Schema using as many generic config keys as possible from `homeassistant.const`
|
|
4. If your component has platforms, define a `PLATFORM_SCHEMA` instead of a `CONFIG_SCHEMA`.
|
|
5. If using a `PLATFORM_SCHEMA` to be used with `EntityComponent`, import base from `homeassistant.helpers.config_validation`
|
|
6. Never depend on users adding things to `customize` to configure behavior inside your component.
|
|
|
|
### 3. Component/platform communication
|
|
|
|
1. If you need to share global data with platforms, use the dictionary `hass.data`. `hass.data[DATA_XY]` while `XY` is the component is preferred over `hass.data[DOMAIN]`.
|
|
2. If the component fetches data that causes its related platform entities to update, you can notify them using the dispatcher code in `homeassistant.helpers.dispatcher`.
|
|
|
|
|
|
### 4. Communication with devices/services
|
|
|
|
1. All API specific code has to be part of a third party library hosted on PyPi. Home Assistant should only interact with objects and not make direct calls to the API.
|
|
|
|
```python
|
|
# bad
|
|
status = requests.get(url('/status'))
|
|
|
|
# good
|
|
from phue import Bridge
|
|
bridge = Bridge(...)
|
|
status = bridge.status()
|
|
```
|
|
|
|
### 5. Limit initial pull request to Minimum Viable Product (MVP)
|
|
Large pull requests mean there is a larger chance of finding problems that need to be addressed, and more code that needs to be reviewed between every requested change. Limit the initial pull request to the minimum functionality needed for someone to get value out of the integration. Once the initial pull request is merged, you can submit additional PRs for the remaining features. This allows reviewers to sign off on smaller chunks of code one at a time, and lets us get your new integration/features in sooner. **Pull requests containing large code dumps (> 800 line adds excluding tests) will not be a priority for review and may be closed.** Limit MVPs to the following:
|
|
- A single platform
|
|
- No custom services
|
|
- Loaded via `configuration.yaml` _or_ config flow (if `configuration.yaml` cannot be used)
|
|
- No other features outside of supporting the single platform
|
|
|
|
### 6. Event names
|
|
Prefix component event names with the component name itself. For example, use `netatmo_person` instead of `person` for the `netatmo` component.
|
|
|
|
### 7. Tests
|
|
Strongly consider adding tests for your component to ensure it works correctly. Pull Requests with tests are treated with a higher priority than those without. |