diff --git a/docs/core/entity.md b/docs/core/entity.md index 512d5f91..4247df87 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -84,6 +84,12 @@ To avoid calculations in a property method, set the corresponding [entity class | supported_features | int | None | `None` | Flag features supported by the entity. Domains specify their own. | translation_key | str | None | `None` | A key for looking up translations of the entity's state in [`entity` section of the integration's `strings.json`](/docs/internationalization/core#state-of-entities). +:::warning +It's allowed to change `device_class`, `supported_features` or any property included in a domain's `capability_attributes`. However, since these entity properties often are not expected to change at all and some entity consumers may not be able to update them at a free rate, we recommend only changing them when absolutely required and at a modest interval. + +As an example, such changes will cause voice assistant integrations to resynchronize with the supporting cloud service. +::: + :::warning Entities that generate a significant amount of state changes can quickly increase the size of the database when the `extra_state_attributes` also change frequently. Minimize the number of `extra_state_attributes` for these entities by removing non-critical attributes or creating additional `sensor` entities. :::