Deprecate timer start optional duration parameter (#93471)

* Deprecate timer start option duration parameter

* Add test

* Fix strings

* breaks_in_ha_version

* strings

* Mod string

homeassistant/components/timer/__init__.py

@@ -22,6 +22,7 @@ from homeassistant.helpers import collection
 import homeassistant.helpers.config_validation as cv
 from homeassistant.helpers.entity_component import EntityComponent
 from homeassistant.helpers.event import async_track_point_in_utc_time
+from homeassistant.helpers.issue_registry import IssueSeverity, async_create_issue
 from homeassistant.helpers.restore_state import RestoreEntity
 import homeassistant.helpers.service
 from homeassistant.helpers.storage import Store
@@ -303,6 +304,18 @@ class Timer(collection.CollectionEntity, RestoreEntity):
     @callback
     def async_start(self, duration: timedelta | None = None):
         """Start a timer."""
+        if duration:
+            async_create_issue(
+                self.hass,
+                DOMAIN,
+                "deprecated_duration_in_start",
+                breaks_in_ha_version="2024.3.0",
+                is_fixable=True,
+                is_persistent=True,
+                severity=IssueSeverity.WARNING,
+                translation_key="deprecated_duration_in_start",
+            )
+
         if self._listener:
             self._listener()
             self._listener = None

homeassistant/components/timer/strings.json

@@ -63,5 +63,18 @@
         }
       }
     }
+  },
+  "issues": {
+    "deprecated_duration_in_start": {
+      "title": "The timer start service duration parameter is being removed",
+      "fix_flow": {
+        "step": {
+          "confirm": {
+            "title": "[%key:component::timer::issues::deprecated_duration_in_start::title%]",
+            "description": "The timer service `timer.start` optional duration parameter is being removed and use of it has been detected. To change the duration please create a new timer.\n\nPlease remove the use of the `duration` parameter in the `timer.start` service in your automations and scripts and select **submit** to close this issue."
+          }
+        }
+      }
+    }
   }
 }

tests/components/timer/test_init.py

@@ -46,7 +46,11 @@ from homeassistant.const import (
 )
 from homeassistant.core import Context, CoreState, HomeAssistant, State
 from homeassistant.exceptions import HomeAssistantError, Unauthorized
-from homeassistant.helpers import config_validation as cv, entity_registry as er
+from homeassistant.helpers import (
+    config_validation as cv,
+    entity_registry as er,
+    issue_registry as ir,
+)
 from homeassistant.helpers.restore_state import StoredState, async_get
 from homeassistant.setup import async_setup_component
 from homeassistant.util.dt import utcnow
@@ -266,7 +270,9 @@ async def test_methods_and_events(hass: HomeAssistant) -> None:
 
 
 @pytest.mark.freeze_time("2023-06-05 17:47:50")
-async def test_start_service(hass: HomeAssistant) -> None:
+async def test_start_service(
+    hass: HomeAssistant, issue_registry: ir.IssueRegistry
+) -> None:
     """Test the start/stop service."""
     await async_setup_component(hass, DOMAIN, {DOMAIN: {"test1": {CONF_DURATION: 10}}})
 
@@ -311,6 +317,12 @@ async def test_start_service(hass: HomeAssistant) -> None:
         blocking=True,
     )
     await hass.async_block_till_done()
+
+    # Ensure an issue is raised for the use of this deprecated service
+    assert issue_registry.async_get_issue(
+        domain=DOMAIN, issue_id="deprecated_duration_in_start"
+    )
+
     state = hass.states.get("timer.test1")
     assert state
     assert state.state == STATUS_ACTIVE