Deprecate use of config entry listener with reloading methods in config entries (#169198)

Co-authored-by: Copilot <copilot@github.com>

homeassistant/config_entries.py

@@ -3093,6 +3093,13 @@ class ConfigFlow(ConfigEntryBaseFlow):
             # Existing config entry present, and the
             # entry data just changed
             should_reload = True
+            if entry.update_listeners:
+                report_usage(
+                    "has an update listener and should use it for scheduling a reload",
+                    core_behavior=ReportBehavior.LOG,
+                    breaks_in_ha_version="2026.12.0",
+                    integration_domain=self.handler,
+                )
         elif (
             self.source in DISCOVERY_SOURCES
             and entry.state is ConfigEntryState.SETUP_RETRY
@@ -3492,6 +3499,13 @@ class ConfigFlow(ConfigEntryBaseFlow):
             options=options,
         )
         if reload_even_if_entry_is_unchanged or result:
+            if entry.update_listeners:
+                report_usage(
+                    "has an update listener and should use it for scheduling a reload",
+                    core_behavior=ReportBehavior.LOG,
+                    breaks_in_ha_version="2026.12.0",
+                    integration_domain=self.handler,
+                )
             self.hass.config_entries.async_schedule_reload(entry.entry_id)
         if reason is UNDEFINED:
             reason = "reauth_successful"

tests/test_config_entries.py

@@ -7030,6 +7030,68 @@ async def test_update_entry_and_reload(
     assert len(comp.async_unload_entry.mock_calls) == calls_entry_load_unload[1]
 
 
+async def test_update_entry_and_reload_with_listener_logs(
+    hass: HomeAssistant, caplog: pytest.LogCaptureFixture
+) -> None:
+    """Test updating an entry and reloading with a config entry listener logs deprecation."""
+    entry = MockConfigEntry(
+        domain="comp",
+        unique_id="1234",
+        title="Test",
+        data={"vendor": "data"},
+        options={"vendor": "options"},
+    )
+    entry.add_to_hass(hass)
+    entry.add_update_listener(AsyncMock())
+
+    comp = MockModule(
+        "comp",
+        async_setup_entry=AsyncMock(return_value=True),
+        async_unload_entry=AsyncMock(return_value=True),
+    )
+    mock_integration(hass, comp)
+    mock_platform(hass, "comp.config_flow", None)
+
+    await hass.config_entries.async_setup(entry.entry_id)
+
+    class MockFlowHandler(config_entries.ConfigFlow):
+        """Define a mock flow handler."""
+
+        VERSION = 1
+
+        async def async_step_reauth(self, data):
+            """Mock Reauth."""
+            self._abort_if_unique_id_configured(updates={"vendor": "data2"})
+
+        async def async_step_reconfigure(self, data):
+            """Mock Reconfigure."""
+            return self.async_update_reload_and_abort(entry, data={"vendor": "data3"})
+
+    message = (
+        "Detected that integration 'comp' has an update listener and should use it"
+        " for scheduling a reload. This will stop working in Home Assistant 2026.12.0"
+    )
+
+    with (
+        mock_config_flow("comp", MockFlowHandler),
+        patch.object(frame, "_REPORTED_INTEGRATIONS", set()),
+    ):
+        await entry.start_reauth_flow(hass)
+    await hass.async_block_till_done()
+
+    assert message in caplog.text
+    caplog.clear()
+
+    with (
+        mock_config_flow("comp", MockFlowHandler),
+        patch.object(frame, "_REPORTED_INTEGRATIONS", set()),
+    ):
+        await entry.start_reconfigure_flow(hass)
+    await hass.async_block_till_done()
+
+    assert message in caplog.text
+
+
 @pytest.mark.parametrize(
     ("source", "reason"),
     [