From 51d5722c2ce7dae6efd67c8afbd5836f4bd6d271 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Niko=20F=C3=B6hr?= <fohrloop@gmail.com>
Date: Fri, 20 Sep 2024 16:36:42 +0300
Subject: [PATCH] Update the migration guide for 0.8.0 and 0.10.0 (#397)

Closes: #368
---
 docs/source/migration.md | 51 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/docs/source/migration.md b/docs/source/migration.md
index cabbfdc0..a29d9c7a 100644
--- a/docs/source/migration.md
+++ b/docs/source/migration.md
@@ -1,7 +1,52 @@
 # Migration Guide
+## Migration Guide: 0.10.0
+
+### on_fail action
+
+As the previous default `on_fail` value of {func}`keep.running <wakepy.keep.running>` and {func}`keep.presenting <wakepy.keep.presenting>` was "error" (=raise Exception if activation fails) and the new default is "warn", *if you still wish to raise Exceptions*, use the following:
+
+  
+```{code-block} python
+from wakepy import keep
+
+with keep.running(on_fail="error"):
+  do_something()
+```
+
+
+## Migration Guide: 0.8.0
+
+### Decision when keepawake fails
+
+The old way (wakepy <= 0.8.0) was:
+
+```{code-block} python
+from wakepy import keep
+
+with keep.running() as m:
+  if not m.success:
+    # optional: signal to user?
+  do_something()
+```
+
+On wakepy 0.8.0 one should use the `on_fail` parameter for controlling what to do if activation fails. See the [Controlling the on_fail action](#on-fail-action) in the [User Guide](#user-guide).  A minimum example would be:
+
+
+```{code-block} python
+from wakepy import keep
+
+with keep.running(on_fail=react_on_failure) as m:   
+    do_something()
+
+def react_on_failure(result: ActivationResult):
+    print(f'Failed to keep system awake using {result.mode_name} mode')
+```
+
+See the {class}`ActivationResult <wakepy.ActivationResult>` docs for more details on what's available on the `result` object. The `m.success` does not exist anymore, as the type of `m` is now an instance of {class}`Mode <wakepy.Mode>`. It has {attr}`Mode.active <wakepy.Mode.active>`. and {attr}`Mode.activation_result <wakepy.Mode.activation_result>`. as well as {attr}`Mode.active_method <wakepy.Mode.active_method>` and  {attr}`Mode.used_method <wakepy.Mode.used_method>`.
+
 ## Migration Guide: 0.7.0
 
-- When migrating from wakepy <=0.6.0 to >=0.7.0
+- When migrating from wakepy <=0.6.0 to 0.7.0
 -  `set_keepawake` and `unset_keepawake` and `keepawake`: Replace with `keep.running` or `keep.presenting`, whichever makes sense in the application.
 
 ### Python API
@@ -23,7 +68,7 @@ do_something()
 unset_keepawake()
 ```
 
-#### wakepy >=0.7.0
+#### wakepy 0.7.0
 ```{code-block} python
 from wakepy import keep
 
@@ -52,7 +97,7 @@ with keep.presenting() as m:
 ```
 wakepy -s
 ```
-### wakepy >= 0.7.0
+### wakepy 0.7.0
 ```
 wakepy -p
 ```