Raise repair issues when the user needs to act

This is a Gold rule. In quality_scale.yaml, it is called repair-issues.

When something is wrong that the user can fix, the integration raises a repair issue. It shows up under Settings > System > Repairs, with an explanation of the problem and what to do about it. When the integration can fix the problem itself after the user confirms, it adds a repair flow that guides the user through it.

Repair issues must be actionable. Do not raise one just to say that something is wrong, when the user cannot do anything about it.

Logs are where problems go to be ignored. A repair issue is where Home Assistant tells the user, in plain language and in their own language, that something needs their attention, and what to do. It turns "my integration stopped working" into "update the firmware of your device to version 2.0".

An issue the user cannot act on is noise. It teaches users to ignore the repairs, so they miss the ones that matter.

On setup, the integration checks the version of a local service. When it is too old, it raises a repair issue, and stops:

async def async_setup_entry(
    hass: HomeAssistant, entry: MyConfigEntry
) -> bool:
    """Set up My integration from a config entry."""
    client = MyClient(entry.data[CONF_HOST])
    version = await client.get_version()

    if version < MINIMUM_VERSION:
        ir.async_create_issue(
            hass,
            DOMAIN,
            "outdated_version",
            is_fixable=False,
            severity=ir.IssueSeverity.ERROR,
            translation_key="outdated_version",
            translation_placeholders={"minimum": str(MINIMUM_VERSION)},
        )
        raise ConfigEntryError(
            translation_domain=DOMAIN,
            translation_key="outdated_version",
        )

    ir.async_delete_issue(hass, DOMAIN, "outdated_version")
    ...

ir is homeassistant.helpers.issue_registry. The text of the issue lives in the issues section of strings.json, next to the message of the exception:

{
  "exceptions": {
    "outdated_version": {
      "message": "My service is out of date."
    }
  },
  "issues": {
    "outdated_version": {
      "title": "My service is out of date",
      "description": "Update My service to version {minimum} or newer."
    }
  }
}

Delete the issue once the problem is solved, like the example does on a successful setup.

• The tests fail when an issue is raised whose translation is missing in strings.json.
• Whether the integration raises issues where users need to act, and only there, is checked in review.

If the integration has no situations where a repair issue is needed, this rule does not apply.