Add dev blog about deprecating @bind_hass and hass.components (#2093)

* Add dev blog about deprecating `@bind_hass` and `hass.components`

* Add note about logging

* Clarify that we start removing @bind_hass in core

* Change version

* Add note about manifest.json

* Apply suggestion

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update message

* Adjust language

---------

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

blog/2024-02-27-deprecate-bind-hass-and-hass-components.md

@@ -0,0 +1,93 @@
+---
+author: Jan-Philipp Benecke
+authorURL: https://github.com/jpbede
+authorImageURL: https://avatars.githubusercontent.com/u/3989428?s=96&v=4
+title: "Deprecate use of @bind_hass and hass.components"
+---
+
+As of Home Assistant 2024.3, we deprecate the use of the `@bind_hass` decorator 
+and thus also the use of `hass.components`.
+Using `hass.components` will issue a warning in the logs.
+Authors of custom integrations are encouraged to update their code 
+to prevent any issues before Home Assistant 2024.9.
+
+Starting from Home Assistant 2024.9, the `@bind_hass` decorator and 
+`hass.components` will be removed and will no longer work.
+
+## Use of `@bind_hass` decorator
+
+Integrations that use the `@bind_hass` decorator should be updated to remove them and pass the `hass` object as first parameter to the function instead:
+
+### New example
+
+```python
+from homeassistant.core import HomeAssistant
+from homeassistant.components.persistent_notification import async_create
+
+def create_notification(hass: HomeAssistant, message: str):
+    """Create a notification."""
+    async_create(
+        hass,
+        message, 
+        title='Important notification'
+    )
+
+async def async_setup(hass: HomeAssistant, config):
+    """Set up the component."""
+    create_notification(hass, "You're already using the latest version!")
+```
+
+### Old example
+
+```python
+from homeassistant.core import HomeAssistant
+from homeassistant.loader import bind_hass
+from homeassistant.components.persistent_notification import async_create
+
+@bind_hass
+def create_notification(hass: HomeAssistant, message: str):
+    """Create a notification."""
+    async_create(
+        hass,
+        message, 
+        title='Important notification'
+    )
+
+async def async_setup(hass: HomeAssistant, config):
+    """Set up the component."""
+    create_notification("You're already using the latest version!")
+```
+
+## Use of `hass.components` 
+
+Integrations that use `hass.components` should be updated to import the functions and classes directly
+from the integration package and pass the `hass` object as first parameter.
+Remember to include the imported components under `dependencies` in your `manifest.json`.
+
+### New example
+
+```python
+from homeassistant.core import HomeAssistant
+from homeassistant.components.persistent_notification import async_create
+
+async def async_setup(hass: HomeAssistant, config):
+    """Set up the component."""
+    async_create(
+        hass, 
+        "You're already using the latest version!", 
+        title='Important notification'
+    )
+```
+
+### Old example
+
+```python
+from homeassistant.core import HomeAssistant
+
+async def async_setup(hass: HomeAssistant, config):
+    """Set up the component."""
+    hass.components.persistent_notification.async_create(
+        "You're already using the latest version!", 
+        title='Important notification'
+    )
+```

docs/auth_permissions.md

@@ -262,7 +262,7 @@ from homeassistant.components import websocket_api
 
 
 async def async_setup(hass, config):
-    hass.components.websocket_api.async_register_command(websocket_create)
+    websocket_api.async_register_command(hass, websocket_create)
     return True
 
 

docs/frontend/extending/websocket-api.md

@@ -81,10 +81,12 @@ async def ws_handle_thumbnail(
 With all pieces defined, it's time to register the command. This is done inside your setup method.
 
 ```python
+from homeassistant.components import websocket_api
+
 async def async_setup(hass, config):
     """Setup of your component."""
-    hass.components.websocket_api.async_register_command(ws_get_panels)
-    hass.components.websocket_api.async_register_command(ws_handle_thumbnail)
+    websocket_api.async_register_command(hass, ws_get_panels)
+    websocket_api.async_register_command(hass, ws_handle_thumbnail)
 ```
 
 ## Calling the command from the frontend (JavaScript)