From 5b0df150913a189471c5620819978b35fe19e468 Mon Sep 17 00:00:00 2001
From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
Date: Mon, 15 Apr 2024 14:03:59 +0200
Subject: [PATCH] Operating system: add steps on updating HA OS (#32320)

* Operating system: add steps on updating HA OS

* Fix markdown

* Update source/common-tasks/os.markdown

Co-authored-by: Stefan Agner <stefan@agner.ch>

---------

Co-authored-by: Stefan Agner <stefan@agner.ch>
---
 source/_includes/common-tasks/update.md |  6 ++--
 source/common-tasks/container.markdown  |  3 ++
 source/common-tasks/core.markdown       |  3 ++
 source/common-tasks/os.markdown         | 44 +++++++++++++++++++++++++
 source/common-tasks/supervised.markdown |  3 ++
 5 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/source/_includes/common-tasks/update.md b/source/_includes/common-tasks/update.md
index 1df848b0d29..00498602479 100644
--- a/source/_includes/common-tasks/update.md
+++ b/source/_includes/common-tasks/update.md
@@ -1,8 +1,6 @@
-## Update
+Best practice for updating Home Assistant Core:
 
-Best practice for updating a Home Assistant installation:
-
-1. Backup your installation{% if page.installation == "os" or page.installation == "supervised" %}, using the backup functionality Home Assistant offers{% endif %}.
+1. Backup your installation{% if page.installation == "os" or page.installation == "supervised" %}, using the [backup functionality](/common-tasks/os/#backups) Home Assistant offers{% endif %}.
 2. Check the release notes for backward-incompatible changes on [Home Assistant release notes](/blog/categories/core/). Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (`CTRL + f` / `CMD + f`) and search for **Backward-incompatible changes**.
 {% if page.installation == "os" or page.installation == "supervised" %}
 3. Select **Create backup before updating** in case you encounter an issue that requires a rollback.
diff --git a/source/common-tasks/container.markdown b/source/common-tasks/container.markdown
index 18464daa94c..bba727053b6 100644
--- a/source/common-tasks/container.markdown
+++ b/source/common-tasks/container.markdown
@@ -3,6 +3,9 @@ title: "Common tasks - Container"
 description: "Common tasks for Home Assistant Container"
 installation: container
 ---
+
+## Update
+
 {% include common-tasks/update.md %}
 {% include common-tasks/specific_version.md %}
 {% include common-tasks/beta_version.md %}
diff --git a/source/common-tasks/core.markdown b/source/common-tasks/core.markdown
index 04066e649f2..60ea197ac7e 100644
--- a/source/common-tasks/core.markdown
+++ b/source/common-tasks/core.markdown
@@ -3,6 +3,9 @@ title: "Common tasks - Core"
 description: "Common tasks for Home Assistant Core"
 installation: core
 ---
+
+## Update
+
 {% include common-tasks/update.md %}
 {% include common-tasks/specific_version.md %}
 {% include common-tasks/beta_version.md %}
diff --git a/source/common-tasks/os.markdown b/source/common-tasks/os.markdown
index f1027abf4b7..b024344dfb1 100644
--- a/source/common-tasks/os.markdown
+++ b/source/common-tasks/os.markdown
@@ -6,6 +6,50 @@ installation_name: "Operating System"
 ---
 This section will provide guides to some common tasks and information which you will need in order to run, maintain, and edit your Home Assistant OS system. For further details on any particular subject, make sure to refer to the documentation for specific add-ons or topics listed here.
 
+## Updating Home Assistant
+
+If you have the {% term "Home Assistant Operating System" %} installed, you receive update notifications from different components:
+
+- {% term "Home Assistant Operating System" %}
+- {% term "Home Assistant Supervisor" %}
+- {% term "Home Assistant Core" %}
+- Add-ons, if you have any installed
+
+### Updating the Home Assistant Operating System
+
+Updates of the {% term "Home Assistant Operating System" %} are independent of other updates. They do not trigger repair issues and are usually backward-compatible.
+
+#### Prerequisites
+
+- [Backup](/common-tasks/os/#backups) your installation.
+  - Make sure the backup is downloaded and stored outside of the system.
+  - So that you can restore from that backup in case there is an issue with the system.
+
+#### To update the Home Assistant Operating System
+
+{% tabbed_block %}
+
+- title: Using the UI
+  content: |
+
+    1. Open the **Settings** panel.
+    2. On the top you will be presented with an update notification.
+
+    _If you do not see that notification, in the top right, select the three dots menu and select **Check for updates**"._
+
+- title: Using the CLI
+  content: |
+
+    ```bash
+    ha os update
+    ```
+
+    _This updates to the latest version. If you want to update to a specific version instead, use  `ha os update --version 12.0`._
+
+{% endtabbed_block %}
+
+### Updating Home Assistant Core
+
 {% include common-tasks/update.md %}
 {% include common-tasks/specific_version.md %}
 {% include common-tasks/beta_version.md %}
diff --git a/source/common-tasks/supervised.markdown b/source/common-tasks/supervised.markdown
index 23adfe85603..d3dc28b5d61 100644
--- a/source/common-tasks/supervised.markdown
+++ b/source/common-tasks/supervised.markdown
@@ -4,6 +4,9 @@ description: "Common tasks for Home Assistant Supervised"
 installation: supervised
 installation_name: Supervised
 ---
+
+## Update
+
 {% include common-tasks/update.md %}
 {% include common-tasks/specific_version.md %}
 {% include common-tasks/beta_version.md %}