Add template migration examples

source/_integrations/template.markdown

@@ -2792,3 +2792,359 @@ The blueprint can now be used for creating template entities.
 Event `event_template_reloaded` is fired when Template entities have been reloaded and entities thus might have changed.
 
 This event has no additional data.
+
+## Legacy template deprecation migration guide
+
+Legacy template entities are deprecated and will be removed in Home Assistant 2026.6.0. The deprecated template entities will produce a repair that guides you through the migration.
+
+### Migrating a legacy sensor into a new template section
+
+This example covers how to migrate a legacy template sensor into modern syntax.
+
+Take the example `configuration.yaml` file
+
+{% raw %}
+```yaml
+# configuration.yaml
+sensor:
+# SNMP Configuration
+- platform: snmp
+  host: 192.168.1.32
+  baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+# Legacy template configuration
+- platform: template
+  sensors:
+    my_light_count:
+      friendly_name: Total lights on
+      unique_id: sa892hfa9sdf8
+      value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+```
+
+{% endraw %}
+To get started with the migration:
+
+1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
+
+    Delete the following YAML from `configuration.yaml` file.
+
+{% raw %}
+    ```yaml
+    # Legacy template configuration
+    - platform: template
+      sensors:
+        my_light_count:
+          friendly_name: Total lights on
+          unique_id: sa892hfa9sdf8
+          value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+      ```
+{% endraw %}
+
+      Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:
+
+    ```yaml
+    # configuration.yaml
+    sensor:
+    # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+    ```
+
+1. Add the modern syntax provided by the repair.
+
+    The repair would provide the following YAML.
+
+  {% raw %}
+    ```yaml
+    template:
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+   {% endraw %}
+
+    This YAML should be added to the `template:` section inside `configuration.yaml`.
+
+{% raw %}
+    ```yaml
+    # configuration.yaml
+    sensor:
+      # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+    # Copied example
+    template:
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+    {% endraw %}
+
+    If you are migrating multiple template entities, ensure there is only 1 `template:` section.  Do not keep duplicate `template:` sections.
+
+{% raw %}
+    ```yaml
+    # configuration.yaml
+    sensor:
+      # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+    template:
+
+    # Migrated sensor
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+
+    # Migrated cover
+    - cover:
+      - default_entity_id: cover.garage
+        name: Garage Cover
+        state: '{{ is_state(''binary_sensor.relay'', ''on'') }}'
+
+    # Migrated light
+    - light:
+      - default_entity_id: light.skylight
+        name: Skylight
+        state: '{{ is_state(''binary_sensor.crank'', ''on'') }}'
+    ```
+{% endraw %}
+
+1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**.  Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.
+
+### Migrating a legacy sensor into an existing template section
+
+This example covers how to migrate a legacy template sensor into modern syntax.
+
+Take the example `configuration.yaml` file
+
+{% raw %}
+```yaml
+# configuration.yaml
+sensor:
+# SNMP Configuration
+- platform: snmp
+  host: 192.168.1.32
+  baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+# Legacy template configuration
+- platform: template
+  sensors:
+    my_light_count:
+      friendly_name: Total lights on
+      unique_id: sa892hfa9sdf8
+      value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+
+template:
+# Existing modern template
+- binary_sensor:
+  - name: Bright Outside
+    state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
+```
+{% endraw %}
+
+To get started with the migration:
+
+1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
+
+    Delete the following YAML from `configuration.yaml` file.
+
+{% raw %}
+    ```yaml
+    # Legacy template configuration
+    - platform: template
+      sensors:
+        my_light_count:
+          friendly_name: Total lights on
+          unique_id: sa892hfa9sdf8
+          value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+      ```
+{% endraw %}
+
+      Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:
+
+{% raw %}
+    ```yaml
+    # configuration.yaml
+    sensor:
+    # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+    template:
+    # Existing modern template
+    - binary_sensor:
+      - name: Bright Outside
+        state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
+    ```
+{% endraw %}
+
+1. Add the modern syntax provided by the repair.
+
+    The repair would provide the following YAML.
+
+  {% raw %}
+    ```yaml
+    template:
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+{% endraw %}
+
+    This YAML should be added to the `template:` section inside `configuration.yaml`.
+
+{% raw %}
+    ```yaml
+    # configuration.yaml
+    sensor:
+      # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+    template:
+    # Existing modern template
+    - binary_sensor:
+      - name: Bright Outside
+        state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
+
+    # Copied example
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+{% endraw %}
+
+    In this example, `configuration.yaml` already had a `template:` section.  When copying the YAML, make sure to avoid adding double `template:` sections.
+
+1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**.  Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.
+
+### Migrating a sensor from an included file to an included file
+
+This example covers how to migrate a legacy template sensor into modern syntax when the sensor exists in an included `sensors.yaml` file.
+
+Take the example configuration. It's a configuration that is split between 3 files, `configuration.yaml`, `sensors.yaml`, and `templates.yaml`.
+
+```yaml
+# configuration.yaml
+sensor: !include sensors.yaml
+template: !include templates.yaml
+```
+
+{% raw %}
+```yaml
+# sensors.yaml
+
+# SNMP Configuration
+- platform: snmp
+  host: 192.168.1.32
+  baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+
+# Legacy template configuration
+- platform: template
+  sensors:
+    my_light_count:
+      friendly_name: Total lights on
+      unique_id: sa892hfa9sdf8
+      value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+```
+
+{% endraw %}
+
+{% raw %}
+```yaml
+# templates.yaml
+
+# Existing modern template
+- binary_sensor:
+  - name: Bright Outside
+    state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
+```
+{% endraw %}
+
+To get started with the migration:
+
+1. Remove the `sensor` template definition from the `sensors.yaml` section.
+
+    Delete the following YAML from `sensors.yaml` file.
+
+{% raw %}
+    ```yaml
+    # Legacy template configuration
+    - platform: template
+      sensors:
+        my_light_count:
+          friendly_name: Total lights on
+          unique_id: sa892hfa9sdf8
+          value_template: "{{ states.light | selectattr('state', 'eq', 'on') | list | count }}"
+      ```
+
+{% endraw %}
+      Make sure to keep all the other platforms in the sensor file. Your `sensors.yaml` file would look like this after the change:
+
+
+    ```yaml
+    # sensors.yaml
+
+    # SNMP Configuration
+    - platform: snmp
+      host: 192.168.1.32
+      baseoid: 1.3.6.1.4.1.2021.10.1.3.1
+    ```
+
+2. Add the modern syntax provided by the repair.
+
+    The repair would provide the following YAML.
+
+  {% raw %}
+    ```yaml
+    template:
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+
+  {% endraw %}
+    This YAML should be added to the `templates.yaml` file.
+
+{% raw %}
+    ```yaml
+    # templates.yaml
+
+    # Existing modern template
+    - binary_sensor:
+      - name: Bright Outside
+        state: "{{ states('sensor.lux_value') | float(0) > 10 }}"
+
+    # Copied example
+    - sensor:
+      - default_entity_id: sensor.my_light_count
+        name: Total lights on
+        unique_id: sa892hfa9sdf8
+        state: '{{ states.light | selectattr(''state'', ''eq'', ''on'') | list | count }}'
+    ```
+
+{% endraw %}
+
+    In this example, `configuration.yaml` already has a `template: !include templates.yaml`.  When copying the yaml, make sure to avoid adding the `template:` section inside `templates.yaml`.
+
+1. Restart Home Assistant by going to **Settings** three dotted menu and selecting **Restart Home Assistant**.  Or reload template entities by going to **Developer tools** **YAML** tab and selecting the **Template entities** reload button.