From 63ce526339cc133d9262726cea40053f3e57b7cb Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Mon, 29 Aug 2022 13:54:04 +0200
Subject: [PATCH] Document the issue registry (#1447)

* Document the issue registry

* Apply suggestions from code review

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

* Tweak language

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
---
 docs/core/platform/repairs.md | 52 +++++++++++++++++++++++++++++++++
 docs/issue_registry_index.md  | 54 +++++++++++++++++++++++++++++++++++
 sidebars.js                   |  7 +++++
 3 files changed, 113 insertions(+)
 create mode 100644 docs/core/platform/repairs.md
 create mode 100644 docs/issue_registry_index.md

diff --git a/docs/core/platform/repairs.md b/docs/core/platform/repairs.md
new file mode 100644
index 00000000..d622d618
--- /dev/null
+++ b/docs/core/platform/repairs.md
@@ -0,0 +1,52 @@
+---
+title: "Repairs"
+---
+
+A fixable [repairs issue](/docs/issue_registry_index) may optionally be repaired by a custom repairs flow.
+
+This is done by adding the function (`async_create_fix_flow`) to `repairs.py`
+
+## Adding support
+
+Create a new file in your integration folder called `repairs.py` and add code according to the pattern below.
+
+
+```python
+from __future__ import annotations
+
+import voluptuous as vol
+
+from homeassistant import data_entry_flow
+from homeassistant.components.repairs import ConfirmRepairFlow, RepairsFlow
+from homeassistant.core import HomeAssistant
+
+
+class Issue1RepairFlow(RepairsFlow):
+    """Handler for an issue fixing flow."""
+
+    async def async_step_init(
+        self, user_input: dict[str, str] | None = None
+    ) -> data_entry_flow.FlowResult:
+        """Handle the first step of a fix flow."""
+
+        return await (self.async_step_confirm())
+
+    async def async_step_confirm(
+        self, user_input: dict[str, str] | None = None
+    ) -> data_entry_flow.FlowResult:
+        """Handle the confirm step of a fix flow."""
+        if user_input is not None:
+            return self.async_create_entry(title="", data={})
+
+        return self.async_show_form(step_id="confirm", data_schema=vol.Schema({}))
+
+
+async def async_create_fix_flow(
+    hass: HomeAssistant,
+    issue_id: str,
+    data: dict[str, str | int | float | None] | None,
+) -> RepairsFlow:
+    """Create flow."""
+    if issue_id == "issue_1":
+        return Issue1RepairFlow()
+```
diff --git a/docs/issue_registry_index.md b/docs/issue_registry_index.md
new file mode 100644
index 00000000..d3c46619
--- /dev/null
+++ b/docs/issue_registry_index.md
@@ -0,0 +1,54 @@
+---
+title: Repairs Issue Registry
+---
+
+The repairs issue registry is a registry where Home Assistant keeps track of repairs issues which should be brought to the user's attention.
+
+## Issue properties
+
+| Attribute |  Type    | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| domain | string | | Domain raising the issue
+| issue_id | string | | An identifier for the issue, must be unique within `domain`
+| breaks_in_ha_version | string | `None` | The version in which the issue is breaking
+| data | dict | `None` | Arbitrary data, not shown to the user
+| is_fixable | boolean | | True if the issue can be automatically fixed
+| is_persistent | boolean | | True if the issue should persists across restarts of Home Assistant
+| issue_domain | string | `None` | Set by integrations creating issues on behalf of other integrations
+| learn_more_url | string | `None` | URL where the user can find more details about an issue
+| severity | IssueSeverity |  | Severity of the issue
+| translation_key | str |  | Translation key with a brief explanation of the issue
+| translation_placeholders | dict | `None` | Placeholders which will be injected in the translation
+
+## Creating an issue
+
+```python
+from homeassistant.helpers import issue_registry as ir
+
+ir.async_create_issue(
+    hass,
+    DOMAIN,
+    "manual_migration",
+    breaks_in_ha_version="2022.9.0",
+    is_fixable=False,
+    severity=IssueSeverity.ERROR,
+    translation_key="manual_migration",
+)
+```
+
+## Deleting an issue
+
+Integrations typically don't need to delete issues, but it may be useful in some cases.
+
+```python
+from homeassistant.helpers import issue_registry as ir
+
+ir.async_delete_issue(hass, DOMAIN, "manual_migration")
+```
+
+## Fixing an issue
+
+If an issue has the `is_fixable` issue set to `True`, the user will be allowed to fix the issue. An issue which is succesfully fixed will be removed from the issue registry.
+
+If the integration can perform some steps to fix an issue or to verify that the user has made the necessary manual steps, it should implement a [`repairs` platform](/docs/core/platform/repairs.md).
+In some cases, fixing an issue may be done by the user by performing some manual steps which can't be verified by the integration, and no repairs platform is needed.
diff --git a/sidebars.js b/sidebars.js
index f677d52a..8d20242a 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -165,6 +165,13 @@ module.exports = {
         dirName: 'core/platform',
       },
     ],
+    Registries: [
+      "area_registry_index",
+      "device_registry_index",
+      "entity_registry_index",
+      "entity_registry_disabled_by",
+      "issue_registry_index",
+    ],
     "Device Automations": [
       "device_automation_index",
       "device_automation_trigger",