Add new method version_is_newer to Update platform (#2307)

* add new method

* apply review comments

* section title

* Update docs/core/entity/update.md

Co-authored-by: G Johansson <goran.johansson@shiftit.se>

* apply review comments

* add blog post

* missing string

* Update blog/2024-09-19-update-version-compare.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update blog/2024-09-19-update-version-compare.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Update blog/2024-09-19-update-version-compare.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* apply review comments

* Apply suggestions from code review

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* update filename date

---------

Co-authored-by: G Johansson <goran.johansson@shiftit.se>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

blog/2024-09-28-update-version-compare.md

@@ -0,0 +1,32 @@
+---
+author: Simone Chemelli
+authorURL: https://github.com/chemelli74
+title: "Version compare for Update platform can now be overwritten"
+---
+
+With the merge of [core PR #124797](https://github.com/home-assistant/core/pull/124797), which will land in Home Assistant Core 2024.10, there is a new method in the update platform: `version_is_newer()`.
+
+Before this change, the compare logic between firmware installed version, new available version and beta version was hardcoded:
+
+```python
+def version_is_newer(self, latest_version: str, installed_version: str) -> bool:
+    """Return True if latest_version is newer than installed_version."""
+    return AwesomeVersion(latest_version) > installed_version
+```
+
+Now the new method allows developers to customize this comparison, writing their own method.
+Here's an example (implemented for Shelly gen1 devices):
+
+```python
+def version_is_newer(self, latest_version: str, installed_version: str) -> bool:
+    """Return True if available version is newer then installed version."""
+    return AwesomeVersion(
+        latest_version,
+        find_first_match=True,
+        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
+    ) > AwesomeVersion(
+        installed_version,
+        find_first_match=True,
+        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
+    )
+```

docs/core/entity/update.md

@@ -47,6 +47,27 @@ Supported features are defined by using values in the `UpdateEntityFeature` enum
 
 ## Methods
 
+### Compare versions
+
+This method should be implemented when needed to override the default version comparison logic.
+Here's an example:
+
+```python
+def version_is_newer(self, latest_version: str, installed_version: str) -> bool:
+    """Return True if latest_version is newer than installed_version."""
+    return AwesomeVersion(
+        latest_version,
+        find_first_match=True,
+        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
+    ) > AwesomeVersion(
+        installed_version,
+        find_first_match=True,
+        ensure_strategy=[AwesomeVersionStrategy.SEMVER],
+    )
+```
+
+It allows developers to specify custom logic for determining if one version is newer than another. First attempt should be based on the strategies provided by the [AwesomeVersion library](https://github.com/ludeeus/awesomeversion?tab=readme-ov-file#awesomeversion-class).
+
 ### Install
 
 This method can be implemented so users can install an offered update directly