Add template migration examples #42149

Petro31 · 2025-12-04T18:11:42Z

Proposed change

Add template migration examples and guides to documentation.

Type of change

Spelling, grammar or other readability improvements (current branch).
Adjusted missing or incorrect information in the current documentation (current branch).
Added documentation for a new integration I'm adding to Home Assistant (next branch).
- I've opened up a PR to add logos and icons in Brands repository.
Added documentation for a new feature I'm adding to Home Assistant (next branch).
Removed stale or deprecated documentation.

Additional information

Link to parent pull request in the codebase:
Link to parent pull request in the Brands repository:
This PR fixes or closes issue: fixes #

Checklist

This PR uses the correct branch, based on one of the following:
- I made a change to the existing documentation and used the current branch.
- I made a change that is related to an upcoming version of Home Assistant and used the next branch.
The documentation follows the Home Assistant documentation standards.

netlify · 2025-12-04T18:11:48Z

✅ Deploy Preview for home-assistant-docs ready!

Name	Link
🔨 Latest commit	`9ae7d4e`
🔍 Latest deploy log	https://app.netlify.com/projects/home-assistant-docs/deploys/6932d85ec5d64e000856fb93
😎 Deploy Preview	https://deploy-preview-42149--home-assistant-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

zweckj · 2025-12-04T19:02:58Z

There's something wrong with the syntax, because CI is failing and the deploy preview hasn’t been built

Petro31 · 2025-12-04T19:22:31Z

I'll take a look

silamon · 2025-12-05T06:21:52Z

Use the raw and endraw around your yaml examples.

zweckj · 2025-12-05T06:28:21Z

Does it make sense to add a block about file inclusions and splitting them in the new structure/folder structure (similar to what you wrote in the forums?

source/_integrations/template.markdown

c0ffeeca7

nice! Thank you, @Petro31, @zweckj, and @silamon 👍

c0ffeeca7 · 2025-12-05T07:45:08Z

I didn't merge it because I don't know if this is for this PR or for a new one #42149 (comment)

zweckj

Just adding some comments so it's a bit more clear which file is which

zweckj · 2025-12-05T07:56:19Z

source/_integrations/template.markdown

+      Make sure to keep all the other platforms in the sensor section.
+
+    ```yaml
+    sensor:


Suggested change

sensor:

# configuration.yaml

sensor:

zweckj · 2025-12-05T07:56:50Z

source/_integrations/template.markdown

+      ```
+{% endraw %}
+
+      Make sure to keep all the other platforms in the sensor section.


Suggested change

Make sure to keep all the other platforms in the sensor section.

Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:

zweckj · 2025-12-05T07:58:05Z

source/_integrations/template.markdown

+
+{% raw %}
+    ```yaml
+    sensor:


Suggested change

sensor:

# configuration.yaml

sensor:

zweckj · 2025-12-05T07:58:28Z

source/_integrations/template.markdown

+      ```
+{% endraw %}
+
+      Make sure to keep all the other platforms in the sensor section.


Suggested change

Make sure to keep all the other platforms in the sensor section.

Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:

zweckj · 2025-12-05T07:59:31Z

source/_integrations/template.markdown

+      ```
+
+{% endraw %}
+      Make sure to keep all the other platforms in the sensor file.


Suggested change

Make sure to keep all the other platforms in the sensor file.

Make sure to keep all the other platforms in the sensor file. Your `sensors.yaml` file would look like this after the change:

zweckj · 2025-12-05T08:03:06Z

I didn't merge it because I don't know if this is for this PR or for a new one #42149 (comment)

either is fine. If you guys are fine with my suggestions, we can merge this one and do it in a follow up

frenck

Some patters to look at. Let's make sure it is a clear step by step process.

Some of my comments can be applied on more places, let's ensure that comments are applied consistently.

../Frenck

Blogging my personal ramblings at frenck.dev

frenck · 2025-12-05T09:17:43Z

source/_integrations/template.markdown

+
+## 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.


Suggested change

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.

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.

frenck · 2025-12-05T09:17:53Z

source/_integrations/template.markdown

+
+This example covers how to migrate a legacy template sensor into modern syntax.
+
+Take the example configuration.yaml file


Suggested change

Take the example configuration.yaml file

Take the example `configuration.yaml` file

frenck · 2025-12-05T09:18:15Z

source/_integrations/template.markdown

+
+1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
+
+    Delete the following yaml from configuration.yaml file.


Suggested change

Delete the following yaml from configuration.yaml file.

Delete the following YAML from the `configuration.yaml` file.

frenck · 2025-12-05T09:18:36Z

source/_integrations/template.markdown

+
+2. Add the modern syntax provided by the repair.
+
+    The repair would provide the following yaml.


Suggested change

The repair would provide the following yaml.

The repair would provide the following YAML.

frenck · 2025-12-05T09:18:48Z

source/_integrations/template.markdown

+    ```
+   {% endraw %}
+
+    This yaml should be added to the `template:` section inside configuration.yaml.


Suggested change

This yaml should be added to the `template:` section inside configuration.yaml.

This YAML should be added to the `template:` section inside `configuration.yaml`.

frenck · 2025-12-05T09:20:15Z

source/_integrations/template.markdown

+
+1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.
+
+    Delete the following yaml from configuration.yaml file.


Suggested change

Delete the following yaml from configuration.yaml file.

Delete the following YAML from the `configuration.yaml` file.

source/_integrations/template.markdown

frenck · 2025-12-05T09:20:47Z

source/_integrations/template.markdown

+
+    **Note**: In this example, configuration.yaml already had a `template:` section.  When copying the yaml, make sure to avoid adding double `template:` sections.
+
+3. Restart Home Assistant or reload template entities.


Let's explain how to do that.

frenck · 2025-12-05T09:20:53Z

source/_integrations/template.markdown

+    ```
+{% endraw %}
+
+    **Note**: In this example, configuration.yaml already had a `template:` section.  When copying the yaml, make sure to avoid adding double `template:` sections.


Note handling needed.

home-assistant · 2025-12-05T09:22:14Z

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

…e directions

zweckj · 2025-12-05T12:37:46Z

For the notes to work properly you might need to change indent. Not 100% sure about this though

Petro31 · 2025-12-05T13:19:17Z

For the notes to work properly you might need to change indent. Not 100% sure about this though

I ended up removing the notes because they always broke numbering system, indented or not. They are now just part of the steps as a regular sentence.

The preview looks good too and it makes sense as a non-note.

Add template migration examples

cef2139

Petro31 requested a review from a team as a code owner December 4, 2025 18:11

home-assistant bot added the current This PR goes into the current branch label Dec 4, 2025

silamon previously approved these changes Dec 5, 2025

View reviewed changes

c0ffeeca7 reviewed Dec 5, 2025

View reviewed changes

Apply sentence-style capitalization

52a0e07

c0ffeeca7 dismissed silamon’s stale review via 52a0e07 December 5, 2025 07:21

c0ffeeca7 reviewed Dec 5, 2025

View reviewed changes

source/_integrations/template.markdown Show resolved Hide resolved

Apply suggestions from code review

b88add8

c0ffeeca7 reviewed Dec 5, 2025

View reviewed changes

c0ffeeca7 previously approved these changes Dec 5, 2025

View reviewed changes

zweckj reviewed Dec 5, 2025

View reviewed changes

frenck requested changes Dec 5, 2025

View reviewed changes

home-assistant bot marked this pull request as draft December 5, 2025 09:22

address comments

e0a3213

Petro31 dismissed c0ffeeca7’s stale review via e0a3213 December 5, 2025 12:20

remove notes that mess up formatting and keep the items as part of th…

5c94af4

…e directions

update restart bullet

3ce1186

Petro31 marked this pull request as ready for review December 5, 2025 12:47

home-assistant bot requested a review from frenck December 5, 2025 12:47

fix lint text

9ae7d4e

silamon approved these changes Dec 5, 2025

View reviewed changes

	Make sure to keep all the other platforms in the sensor section.
	Make sure to keep all the other platforms in the sensor section. Your `configuration.yaml` file would look like this after the change:


		## 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.


		This example covers how to migrate a legacy template sensor into modern syntax.

		Take the example configuration.yaml file

	Take the example configuration.yaml file
	Take the example `configuration.yaml` file


		1. Remove the `sensor` template definition from the `configuration.yaml` `sensor:` section.

		Delete the following yaml from configuration.yaml file.

	Delete the following yaml from configuration.yaml file.
	Delete the following YAML from the `configuration.yaml` file.


		2. Add the modern syntax provided by the repair.

		The repair would provide the following yaml.

	This yaml should be added to the `template:` section inside configuration.yaml.
	This YAML should be added to the `template:` section inside `configuration.yaml`.


		Note: In this example, configuration.yaml already had a `template:` section. When copying the yaml, make sure to avoid adding double `template:` sections.

		3. Restart Home Assistant or reload template entities.

Uh oh!

Add template migration examples #42149

Are you sure you want to change the base?

Add template migration examples #42149

Uh oh!

Conversation

Petro31 commented Dec 4, 2025

Proposed change

Type of change

Additional information

Checklist

Uh oh!

netlify bot commented Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for home-assistant-docs ready!

Uh oh!

zweckj commented Dec 4, 2025

Uh oh!

Petro31 commented Dec 4, 2025

Uh oh!

silamon commented Dec 5, 2025

Uh oh!

zweckj commented Dec 5, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

c0ffeeca7 left a comment

Choose a reason for hiding this comment

Uh oh!

c0ffeeca7 commented Dec 5, 2025

Uh oh!

zweckj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zweckj commented Dec 5, 2025

Uh oh!

frenck left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

netlify bot commented Dec 4, 2025 •

edited

Loading

Petro31 commented Dec 5, 2025 •

edited

Loading