Add deadline for custom components (#4446)

kbx81 · web-flow · commit 278196ace07a · 2024-11-18T08:59:11.000+01:00
diff --git a/components/binary_sensor/custom.rst b/components/binary_sensor/custom.rst
@@ -9,8 +9,8 @@ Custom Binary Sensor
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/climate/custom.rst b/components/climate/custom.rst
@@ -9,8 +9,8 @@ Custom Climate
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/cover/custom.rst b/components/cover/custom.rst
@@ -9,8 +9,8 @@ Custom Cover
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/light/custom.rst b/components/light/custom.rst
@@ -9,8 +9,8 @@ Custom Light Output
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/output/custom.rst b/components/output/custom.rst
@@ -9,8 +9,8 @@ Custom Output
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst
@@ -9,8 +9,8 @@ Custom Sensor Component
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/switch/custom.rst b/components/switch/custom.rst
@@ -9,8 +9,8 @@ Custom Switch
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/components/text_sensor/custom.rst b/components/text_sensor/custom.rst
@@ -9,8 +9,8 @@ Custom Text Sensor
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/custom/custom_component.rst b/custom/custom_component.rst
@@ -9,8 +9,8 @@ Generic Custom Component
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/custom/i2c.rst b/custom/i2c.rst
@@ -9,8 +9,8 @@ Custom I²C Device
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/custom/spi.rst b/custom/spi.rst
@@ -9,8 +9,8 @@ Custom SPI Device
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/custom/uart.rst b/custom/uart.rst
@@ -9,8 +9,8 @@ Custom UART Device
 .. warning::
 
     :ref:`Custom Components are deprecated<a_note_about_custom_components>`, not recommended for new configurations and
-    will be removed from ESPHome in a future release. Please look at creating a real ESPHome component and "importing"
-    it into your configuration with :doc:`/components/external_components`.
+    will be removed from ESPHome in the ``2025.1.0`` release. Please look at creating a real ESPHome component and
+    "importing" it into your configuration with :doc:`/components/external_components`.
 
     You can find some basic documentation on creating your own components at :ref:`contributing_to_esphome`.
 
diff --git a/guides/contributing.rst b/guides/contributing.rst
@@ -1017,7 +1017,10 @@ ESPHome's "custom component" mechanism is a holdover from Home Assistant's featu
 :doc:`/components/external_components` and offered a way to "hack in" support for devices which were not officially
 supported by ESPHome.
 
-ESPHome has since deprecated this feature in favor of :doc:`/components/external_components` for several reasons:
+Why are Custom Components Deprecated?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several reasons for this change.
 
 - Custom components are very fragile:
 
@@ -1026,11 +1029,13 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
     resulting in compiler errors, unexpected behavior and/or crashes.
   - Custom components are difficult to use. You have to manually copy all of the custom component's files into *just
     the right location* on your system or else you will receive compiler errors and the component won't work.
-  - Custom components almost always require C++ code changes when you want them to work even *slightly* differently
-    than the original author intended.
+  - Custom components lack flexibility and almost always require C++ code changes when you want them to work even
+    *slightly* differently than the original author intended/designed. For example, a simple change of input units
+    (``cm`` to ``m``, for example) could require significant changes to the C++ code, depending on how the original
+    author designed the custom component.
 
 - :doc:`/components/external_components` initially require a bit more effort by the developer but are ultimately more
-  robust and easier to use and share:
+  robust and are easier to use and share:
 
   - Just like any other ESPHome component/platform:
 
@@ -1044,7 +1049,8 @@ ESPHome has since deprecated this feature in favor of :doc:`/components/external
 
   - They tend to be more flexible since they are configured in YAML (as opposed to editing C++ code to make changes).
 
-**So what is the difference between custom components and** :doc:`/components/external_components`?
+What's the Difference?
+^^^^^^^^^^^^^^^^^^^^^^
 
 Custom components are typically (more or less) just the :ref:`runtime` part of an ESPHome component/platform. On the
 other hand, :doc:`/components/external_components` are just like any other ESPHome component -- the only difference is
@@ -1058,6 +1064,9 @@ In terms of implementation, custom components just lack the Python part of an ES
 As such, most custom components can be made into :doc:`/components/external_components` simply by adding the required
 Python parts to make the custom component into a proper, complete ESPHome component.
 
+What's Next?
+^^^^^^^^^^^^
+
 We encourage all custom component developers to extend their custom component(s) into proper
 :doc:`/components/external_components`; doing so will make your custom component easier to share and use. As you do so,
 be sure to have a look at the the :ref:`contributing_to_esphome` section above as it walks through ESPHome (component)
