Add blogpost and documentation for the update integration

blog/2022-03-07-update_all_the_things.md

@@ -0,0 +1,17 @@
+---
+author: Joakim Sørensen
+authorURL: https://github.com/ludeeus
+authorImageURL: /img/profile/ludeeus.jpg
+authorTwitter: ludeeus
+title: "Update all the things!🎉"
+---
+
+In Home Assistant Core [2021.12](https://www.home-assistant.io/blog/2021/12/11/release-202112/#brand-new-configuration-panel) we moved updates provided by
+the Supervisor to the Configuration panel, starting with Home Assistant Core 2022.4 this is no longer limited to the Supervisor integration.
+
+All integrations can now provide an update platform (`update.py`) to show and
+perform updates.
+
+Previously we had the `update` device class for the [button entity](/docs/core/entity/button), this is now considered deprecated and you should move to the update platform instead.
+
+For more details on how to implement the update platform in your integration have a look at the [update platform documentation](/docs/core/update_platform)

docs/core/entity/button.md

@@ -9,7 +9,6 @@ It can be compared to a real live momentary switch, push-button, or some other f
 A switch button entity is derived from the  [`homeassistant.components.button.ButtonEntity`](https://github.com/home-assistant/core/blob/dev/homeassistant/components/button/__init__.py),
 and can be helpful for controlling device features like (but not limited to):
 
-- Upgrading firmware
 - Reboot/Restart a device
 - Brew a cup of coffee
 - Reset something (like a counter, filter usage)
@@ -47,4 +46,4 @@ Optionally specifies what type of entity it is. It will possibly map to Google d
 | Value | Description
 | ----- | -----------
 | restart | The button entity restarts the device.
-| update | The button entity updates the software of the device.
+| update | The button entity updates the software of the device. (This device_class is deprecated and you should implement an [update platform](/docs/core/update_platform) instead)

docs/core/update_platform.md

@@ -0,0 +1,63 @@
+---
+title: Update platform
+---
+
+The update platform allow you to provide updates that the user can manage in the configuration panel of the Home Assistant UI[^1].
+
+Add a new `update.py` file to your integration with the 2 public functions
+described below to enable this feature.
+
+:::tip
+
+You can also use the `update` scaffold template.
+
+```shell
+python3 -m script.scaffold --integration [domain] update
+```
+
+:::
+
+## Public functions
+
+The update platform needs 2 public functions to be present in 
+
+### `async_list_updates`
+
+This is where you gather all the updates the integration provides, and return that as a list of `UpdateDescription` objects.
+
+```python
+async def async_list_updates(hass: HomeAssistant) -> list[UpdateDescription]:
+```
+
+### `async_perform_update`
+
+This is the function that will be called when an user starts an update.
+The `identifier` and the  `version` attributes you declared for the `UpdateDescription`  in  `async_list_updates` will be passed to the function.
+
+```python
+async def async_perform_update(
+    hass: HomeAssistant,
+    identifier: str,
+    version: str,
+    **kwargs: Any,
+) -> None:
+```
+
+If you set `supports_backup`  to `True` in `UpdateDescription` a `backup` key will be present in `kwargs` with a `bool` that represent the choice the user made.
+
+## UpdateDescription
+
+The update description provides a interface to describe the update.
+
+Attribute | Type | Description
+-- | -- | --
+`identifier` | `str` | This identifies the update, this attribute is passed to the `async_perform_update` function when the user starts the update.
+`name` | `str` | This is the name of the update that will be show to the user
+`current_version` | `str` | This represent the current version (the version the user updates from)
+`available_version` | `str` | This represents the version that are available (the version the user updates to), this attribute is passed to the `async_perform_update` function as `version` when the user starts the update.
+`changelog_url` | `str` (Optional) | An URL to where the user can get to the changelog for the update.
+`changelog_content` | `str` (Optional) | Markdown formatted changelog content that will be displayed in the update dialog.
+`icon_url` | `str` (Optional) | URL to an icon that will be shown in the UI, if not present it will use the [brands](https://github.com/home-assistant/brands) icon for the integration.
+`supports_backup` | `bool` (Optional) | Set this to `True` if the integration have a way to perform backup before an update take place.
+
+[^1]: _This require the user to have enabled the `update` integration._

sidebars.js

@@ -184,7 +184,7 @@ module.exports = {
       "device_automation_condition",
       "device_automation_action",
     ],
-    Misc: ["development_validation", "development_typing", "instance_url"],
+    Misc: ["development_validation", "development_typing", "instance_url", "core/update_platform"],
   },
   Misc: {
     Introduction: ["misc"],