From 110dc06cae6d9d2e44ff068c71c421433e5e1598 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 2 Sep 2022 16:32:33 +0200 Subject: [PATCH] Document issue registry issue persistence (#1459) Co-authored-by: Paulus Schoutsen --- docs/issue_registry_index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/issue_registry_index.md b/docs/issue_registry_index.md index d3c46619..426d199e 100644 --- a/docs/issue_registry_index.md +++ b/docs/issue_registry_index.md @@ -36,6 +36,20 @@ ir.async_create_issue( ) ``` +## Issue life cycle + +### Issue persistence + +An issue will be kept in the issue registry until it's removed by the integration that created it or by the user [fixing](#fixing-an-issue) it. + +The `is_persistent` flag controls if an issue should be shown to the user after a restart of Home Assistant: +- If the `is_persistent` flag is set on the issue, the issue will be shown again to the user after a restart. Use this for issues that can only be detected when they occur (update failed, unknown service in automation). +- If the `is_persistent` flag is not set on the issue, the issue will not be shown again to the user after a restart until it's created again by its integration. Use this for issues that can be checked for, like low disk space. + +### Ignored issues + +It's possible for the user to "ignore" issues. An ignored issue is ignored until it's explicitly deleted - either by the integration or by the user successfully walking through its [repair flow](#fixing-an-issue) - and then created again. Ignoring an issue takes effect across restarts of Home Assistant regardless of [issue persistence](#issue-persistence). + ## Deleting an issue Integrations typically don't need to delete issues, but it may be useful in some cases.