Deprecate mqtt vacuum with legacy schema (#95836)

* Deprecate mqtt vacuum with legacy schema

* Consistent comments

* Correct comment

* Remove persistence option

* Adjust string, mention restart

* Update deprecation comment

homeassistant/components/mqtt/strings.json

@@ -1,4 +1,14 @@
 {
+  "issues": {
+    "deprecation_mqtt_legacy_vacuum_yaml": {
+      "title": "MQTT vacuum entities with legacy schema found in your configuration.yaml",
+      "description": "MQTT vacuum entities that use the legacy schema are deprecated, please adjust your configuration.yaml and restart Home Assistant to fix this issue."
+    },
+    "deprecation_mqtt_legacy_vacuum_discovery": {
+      "title": "MQTT vacuum entities with legacy schema added through MQTT discovery",
+      "description": "MQTT vacuum entities that use the legacy schema are deprecated, please adjust your devices to use the correct schema and restart Home Assistant to fix this issue."
+    }
+  },
   "config": {
     "step": {
       "broker": {

homeassistant/components/mqtt/vacuum/__init__.py

@@ -1,7 +1,12 @@
 """Support for MQTT vacuums."""
+
+# The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+# and will be removed with HA Core 2024.2.0
+
 from __future__ import annotations
 
 import functools
+import logging
 
 import voluptuous as vol
 
@@ -9,8 +14,10 @@ from homeassistant.components import vacuum
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 from homeassistant.helpers.typing import ConfigType, DiscoveryInfoType
 
+from ..const import DOMAIN
 from ..mixins import async_setup_entry_helper
 from .schema import CONF_SCHEMA, LEGACY, MQTT_VACUUM_SCHEMA, STATE
 from .schema_legacy import (
@@ -24,9 +31,44 @@ from .schema_state import (
     async_setup_entity_state,
 )
 
+_LOGGER = logging.getLogger(__name__)
+
+MQTT_VACUUM_DOCS_URL = "https://www.home-assistant.io/integrations/vacuum.mqtt/"
+
+
+# The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+# and will be removed with HA Core 2024.2.0
+def warn_for_deprecation_legacy_schema(
+    hass: HomeAssistant, config: ConfigType, discovery_data: DiscoveryInfoType | None
+) -> None:
+    """Warn for deprecation of legacy schema."""
+    if config[CONF_SCHEMA] == STATE:
+        return
+
+    key_suffix = "yaml" if discovery_data is None else "discovery"
+    translation_key = f"deprecation_mqtt_legacy_vacuum_{key_suffix}"
+    async_create_issue(
+        hass,
+        DOMAIN,
+        translation_key,
+        breaks_in_ha_version="2024.2.0",
+        is_fixable=False,
+        translation_key=translation_key,
+        learn_more_url=MQTT_VACUUM_DOCS_URL,
+        severity=IssueSeverity.WARNING,
+    )
+    _LOGGER.warning(
+        "Deprecated `legacy` schema detected for MQTT vacuum, expected `state` schema, config found: %s",
+        config,
+    )
+
 
 def validate_mqtt_vacuum_discovery(config_value: ConfigType) -> ConfigType:
     """Validate MQTT vacuum schema."""
+
+    # The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+    # and will be removed with HA Core 2024.2.0
+
     schemas = {LEGACY: DISCOVERY_SCHEMA_LEGACY, STATE: DISCOVERY_SCHEMA_STATE}
     config: ConfigType = schemas[config_value[CONF_SCHEMA]](config_value)
     return config
@@ -34,6 +76,10 @@ def validate_mqtt_vacuum_discovery(config_value: ConfigType) -> ConfigType:
 
 def validate_mqtt_vacuum_modern(config_value: ConfigType) -> ConfigType:
     """Validate MQTT vacuum modern schema."""
+
+    # The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+    # and will be removed with HA Core 2024.2.0
+
     schemas = {
         LEGACY: PLATFORM_SCHEMA_LEGACY_MODERN,
         STATE: PLATFORM_SCHEMA_STATE_MODERN,
@@ -71,6 +117,10 @@ async def _async_setup_entity(
     discovery_data: DiscoveryInfoType | None = None,
 ) -> None:
     """Set up the MQTT vacuum."""
+
+    # The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+    # and will be removed with HA Core 2024.2.0
+    warn_for_deprecation_legacy_schema(hass, config, discovery_data)
     setup_entity = {
         LEGACY: async_setup_entity_legacy,
         STATE: async_setup_entity_state,

homeassistant/components/mqtt/vacuum/schema_legacy.py

@@ -1,4 +1,9 @@
-"""Support for Legacy MQTT vacuum."""
+"""Support for Legacy MQTT vacuum.
+
+The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+and is will be removed with HA Core 2024.2.0
+"""
+
 from __future__ import annotations
 
 from collections.abc import Callable

tests/components/mqtt/test_legacy_vacuum.py

@@ -1,4 +1,8 @@
 """The tests for the Legacy Mqtt vacuum platform."""
+
+# The legacy schema for MQTT vacuum was deprecated with HA Core 2023.8.0
+# and will be removed with HA Core 2024.2.0
+
 from copy import deepcopy
 import json
 from typing import Any
@@ -124,6 +128,31 @@ def vacuum_platform_only():
         yield
 
 
+@pytest.mark.parametrize(
+    ("hass_config", "deprecated"),
+    [
+        ({mqtt.DOMAIN: {vacuum.DOMAIN: {"name": "test", "schema": "legacy"}}}, True),
+        ({mqtt.DOMAIN: {vacuum.DOMAIN: {"name": "test"}}}, True),
+        ({mqtt.DOMAIN: {vacuum.DOMAIN: {"name": "test", "schema": "state"}}}, False),
+    ],
+)
+async def test_deprecation(
+    hass: HomeAssistant,
+    mqtt_mock_entry: MqttMockHAClientGenerator,
+    caplog: pytest.LogCaptureFixture,
+    deprecated: bool,
+) -> None:
+    """Test that the depration warning for the legacy schema works."""
+    assert await mqtt_mock_entry()
+    entity = hass.states.get("vacuum.test")
+    assert entity is not None
+
+    if deprecated:
+        assert "Deprecated `legacy` schema detected for MQTT vacuum" in caplog.text
+    else:
+        assert "Deprecated `legacy` schema detected for MQTT vacuum" not in caplog.text
+
+
 @pytest.mark.parametrize("hass_config", [DEFAULT_CONFIG])
 async def test_default_supported_features(
     hass: HomeAssistant, mqtt_mock_entry: MqttMockHAClientGenerator