Reconfigure step (#2099)

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
Co-authored-by: Franck Nijhof <git@frenck.dev>
Co-authored-by: Erik Montnemery <erik@montnemery.com>

blog/2024-03-21-config-entry-reconfigure-step.md

@@ -0,0 +1,40 @@
+---
+author: G Johansson
+authorURL: https://github.com/gjohansson-ST
+title: "Config Entries can now provide a reconfigure step"
+---
+
+As of Home Assistant Core 2024.4, config entries can now be reconfigured by adding a `reconfigure` step in their config flows.
+
+This is not to replace the optional configuration (`OptionsFlow`) but instead to allow the user to change the setup configuration after a config entry has been created.
+
+### Reconfiguration vs. Reauthentication
+
+The `reconfigure` step does not replace a `reauth` step and they have different purposes.
+
+Reauthentication should be started automatically by the integration in the case of a login/token/etc. is invalidated, so the user has an option to adjust those settings.
+
+Reconfiguration is started by the user from the config entry options menu and should be implemented to update config entry data which are not optional for the integration to work. Authentication issues are handled with a re-authentication flow. ([See reauthentication](/docs/config_entries_config_flow_handler#reauthentication)).
+
+### Example
+
+Examples could be changing the latitude and longitude of a `WeatherEntity` when moving between homes or having a mobile home, changing the communication port of a local device, etc.
+
+To implement the `reconfigure` step, include it in your config flow as:
+
+```python
+import voluptuous as vol
+
+class ExampleConfigFlow(ConfigFlow, domain=DOMAIN):
+    """Config flow for Example integration."""
+
+    async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None):
+        """Add reconfigure step to allow to reconfigure a config entry."""
+        if user_input is not None:
+            pass  # TODO: process user input
+
+        return self.async_show_form(
+            step_id="reconfigure",
+            data_schema=vol.Schema({vol.Required("password"): str}),
+        )
+```

docs/config_entries_config_flow_handler.md

@@ -61,6 +61,7 @@ There are a few step names reserved for system use:
 | `ssdp`      | Invoked if your integration has been discovered via SSDP/uPnP as specified [using `ssdp` in the manifest](creating_integration_manifest.md#ssdp).             |
 | `usb`       | Invoked if your integration has been discovered via USB as specified [using `usb` in the manifest](creating_integration_manifest.md#usb).             |
 | `user`      | Invoked when a user initiates a flow via the user interface or when discovered and the matching and discovery step are not defined.                                                                                                  |
+| `reconfigure`      | Invoked when a user initiates a flow to reconfigure an existing config entry via the user interface.                                                                                                  |
 | `zeroconf`  | Invoked if your integration has been discovered via Zeroconf/mDNS as specified [using `zeroconf` in the manifest](creating_integration_manifest.md#zeroconf). |
 
 ## Unique IDs
@@ -249,12 +250,36 @@ async def async_migrate_entry(hass, config_entry: ConfigEntry):
     return True
 ```
 
+## Reconfigure
+
+A config entry can allow reconfiguration by adding a `reconfigure` step. This provides a way for integrations to allow users to change config entry data without the need to implement an `OptionsFlow` for changing setup data which is not meant to be optional.
+
+This is not meant to handle authentication issues or reconfiguration of such. For that we have the [`reauth`](#reauthentication) step, which should be implemented to automatically start in such case there is an issue with authentication.
+
+```python
+import voluptuous as vol
+
+class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
+    """Config flow for Example integration."""
+
+    async def async_step_reconfigure(self, user_input: dict[str, Any] | None = None):
+        if user_input is not None:
+            pass  # TODO: process user input
+
+        return self.async_show_form(
+            step_id="reconfigure",
+            data_schema=vol.Schema({vol.Required("input_parameter"): str}),
+        )
+```
+
 ## Reauthentication
 
 Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Qualily Scale](integration_quality_scale_index.md). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2).
 
 This example catches an authentication exception in config entry setup in `__init__.py` and instructs the user to visit the integrations page in order to reconfigure the integration.
 
+To allow the user to change config entry data which is not optional (`OptionsFlow`) and not directly related to authentication, for example a changed host name, integrations should implement the [`reconfigure`](#reconfigure) step.
+
 ```python
 
 from homeassistant.config_entries import SOURCE_REAUTH, ConfigEntry