docs: make it clear that cleanups are call only on successful steps

Sponsored-by: author

1 files changed, 18 insertions, 0 deletions

diff --git a/subplot.md b/subplot.md
index 269343b..93f9f4a 100644
--- a/subplot.md
+++ b/subplot.md
@@ -682,6 +682,24 @@ implementation functions:
 * A binding for a "then everything is OK" step, which captures nothing,
   and calls the `check_everything_is_ok` function.
 
+## Step functions and cleanup
+
+A step function must be atomic: either it completes successfully, or
+it cleans up any changes it made before returning an indication of
+failure.
+
+A cleanup function is only called for successfully executed step
+functions.
+
+For example, consider a step that creates and starts a virtual
+machine. The step function creates the VM, then starts it, and if both
+actions succeeds, the step succeeds. A cleanup function for that step
+will stop and delete the VM. The cleanup is only called if the step
+succeeded. If the step function manages to create the VM, but not
+start it, it's the step function's responsibility to delete the VM,
+before it signals failure. The cleanup function won't be called in
+that case.
+
 ### Simple patterns
 
 The simple patterns are of the form `{name}` and match a single word