Proposal: Add helper for deprecating entities

[sdb9696]

Context

It is sometimes necessary for integrations to stop providing an entity. This could be due to a migration to a new entity that provides richer/better support (e.g. switch -> siren, binary_sensor -> event) or could be removing the entity without a replacement for various reasons.

The best practice in these instances is to give users 6 months to migrate any scripts or automations to the new entity. If the entity is being removed with no replacement, I believe it would also be considered best practice to give 6 months notice if possible.

It is a common pattern to implement a check if a deprecated entity is being used in any issues or scripts and create an issue in the issue log accordingly.

• unifi
• harmony
• lutron
• ring

The lutron and ring examples (ring PR was based on the lutron PR) have additional functionality which immediately prevents the deprecated entity being created if it does not already exist, and, if the entity is currently disabled it is deleted from the entity registry.

Once the breaks_in_ha_version is reached the codeowner will need to go back into the codebase to remove the entity (and usually remove the checking and issue creation code.)

Proposal

The proposal is to add a DeprecatedInfo class to the core entity and use this info during the entity_platform setup to determine whether to create the entity and raise issues. The principal advantages are:

• No need for each integration to implement it's own code to decide whether to create/delete deprecated entities and raise issues.
• Common end-user experience when entities are deprecated. i.e. whether they get 6 months, whether the entity registry is cleaned up, whether they get repair issues, what the issue messages are etc.
• No need to remember to go back to the code on the right date and complete the deprecation and remove the checking/raising code.
• Minimal code required by integrations to deprecate an entity.

Some other potential advantages are:

• Potential to provide information or indicators in the UI on deprecated entities before their removal.
• Potential to audit the codebase for DeprecatedInfo classes that have gone past their breaks_in_ha_version and flag for cleanup.

The following draft PR shows a migration from the ring integration implementing it's own checking/issue raising to what a core implementation could look like.

When to raise issues

EDIT: The example raises issues based on the logic in the lutron and ring implementations. i.e. issues are only raised if the entity is referenced used in automations or scripts. Otherwise issues are not raised. If the user disables the entity it will be removed from the entity registry on the next restart.

N.B. The example has issue_items_fn configurable as part of the DeprecatedInfo class. An alternative would be for this to be a non-configurable default function but for now it was a bit too complicated to check scripts and automations from within the entity_platform module.

Other considered alternatives

Do nothing

Keep the status quo of each integration implementing it's own deprecation logic.

Add helper functions but don't extend the core entity and entity_platform

The async_check_create_deprecated function being removed from the integration in the draft PR could be added to homeassistant.helpers.deprecation and imported and called as part of the integration logic to decide whether to create an entity:

    async_add_entities(
        RingBinarySensor(device, listen_coordinator, description)
        for description in BINARY_SENSOR_TYPES
        for device in ring_data.devices.all_devices
        if device.has_capability(description.capability)
+       and async_check_create_deprecated(hass, Platform.BINARY_SENSOR, f"{device.id}-{description.key}", description,)
    )

The advantage of this is that it's less intrusive as the core entity and entity_platform do not need to change.
The disadvantages are:

• More code changes required in an integration to call the check function in any platform where it could be needed.
• It could be more difficult to be aware of the helper function in the first place if it's not a core entity attribute.
• It could lose the advantage of a "Common end-user experience". An integration could decide to use the helper or instead could implement their own custom logic.
• The potential UI advantage above would not be available

[gjohansson-ST]

I think what's missing is the "when/if/how" for notifications to the user in this proposal.
Give a notification to a user if a service is used or exist in an automation/script but what for entities that doesn't provide services? And give a notification to the user for an entity they might not even be using?

[sdb9696]

Updated the proposal to clarify that