Add docs for significant changes (#785)

Co-authored-by: Philip Allgaier <mail@spacegaier.de>

docs/reproduce_state_index.md

@@ -1,5 +1,5 @@
 ---
-title: "Reproduce State / Scene support"
+title: "Supporting Scenes"
 ---
 
 Home Assistant has support for scenes. Scenes are a collection of (partial) entity states. When a scene is activated, Home Assistant will try to call the right services to get the specified scenes in their specified state.

docs/significant_change_index.md

@@ -0,0 +1,36 @@
+---
+title: "Signicant Change Support"
+---
+
+Home Assistant doesn't only collect data, it also exports data to various services. Not all of these services are interested in every change. To help these services filter insignificant changes, your entity integration can add significant change support.
+
+This support is added by creating a `significant_change.py` platform file with a function `async_check_significant_change`.
+
+```python
+from typing import Any, Optional
+from homeassistant.core import callback
+
+@callback
+def async_check_significant_change(
+    hass: HomeAssistant,
+    old_state: str,
+    old_attrs: dict,
+    new_state: str,
+    new_attrs: dict,
+    **kwargs: Any,
+) -> Optional[bool]
+```
+
+This function is passed a state that was previously considered significant and the new state. It is not just passing the last 2 known states in. The function should return a boolean if it is signficiant or not, or `None` if the function doesn't know.
+
+When deciding on significance, make sure you take all known attributes into account. Use device classes to differentiate between entity types.
+
+Here are some examples of insignificant changes:
+
+ - A battery that loses 0.1 % charge
+ - A temperature sensor that changes 0.1 Celsius
+ - A light that changes 2 brightness
+
+Home Assistant will automatically handle cases like `unknown` and `unavailable`.
+
+To add significant state support to an entity integration, run `python3 -m script.scaffold significant_change`.

sidebars.js

@@ -117,10 +117,13 @@ module.exports = {
       "dev_101_services",
       "creating_platform_index",
       "creating_component_generic_discovery",
-      "reproduce_state_index",
       "integration_fetching_data",
       "integration_events",
     ],
+    "Building Entity Integrations": [
+      "reproduce_state_index",
+      "significant_change_index",
+    ],
     "Development Checklist": [
       "development_checklist",
       "creating_component_code_review",