diff --git a/README.md b/README.md index f8068f4a..1f974ce2 100644 --- a/README.md +++ b/README.md @@ -726,7 +726,7 @@ steps: [...] ``` -The step marked defer behaves as follows. +The step marked `defer` behaves as follows. - If `defer: true` is set, run of the step is deferred until finish of the runbook. - Steps marked with `defer` are always run even if the running of intermediate steps fails. diff --git a/docs/designs/defer.md b/docs/designs/defer.md new file mode 100644 index 00000000..54cf3ccb --- /dev/null +++ b/docs/designs/defer.md @@ -0,0 +1,133 @@ +# Behavior of `defer:` + +Authors: @k1low + +Status: Add continuously + +## Objective + +This document describes the `defer:` behavior in runn. + +## Backgroud + +Allow post-processing of the runbook to be described using `defer:` + +## Behavior of `defer:` + +As the name suggests, `defer:` is inspired by the [defer](https://go.dev/blog/defer-panic-and-recover) of the Go programming language. + +Behavior is also similar to the defer of the Go programming language, but some differences. + +The order of run of steps not marked `defer:` are as follows. + +```yaml +# main.yml +steps: + - desc: step 1 + test: true + - desc: step 2 + test: true + - desc: step 3 + test: true + - desc: step 4 + include: + path: include.yml + - desc: step 5 + test: true +``` + +```yaml +# include.yml +steps: + - desc: included step 1 + test: true + - desc: included step 2 + test: true + - desc: included step 3 + test: true +``` + +``` mermaid +flowchart TB + subgraph "(main.yml)" + A[step 1] + B[step 2] + C[step 3] + G[step 5] + end + + subgraph "step 4 (include.yml)" + D[included step 1] + E[included step 2] + F[included step 3] + end + + A --> B + B --> C + C --> D + D --> E + E --> F + F --> G +``` + +The steps with `defer:` are run as follows. + +```yaml +# main.yml +steps: + - desc: step 1 + test: true + - desc: step 2 + defer: true + test: true + - desc: step 3 + defer: true + test: true + - desc: step 4 + include: + path: include.yml + - desc: step 5 + test: true +``` + +```yaml +# include.yml +steps: + - desc: included step 1 + test: true + - desc: included step 2 + defer: true + test: true + - desc: included step 3 + test: true +``` + +``` mermaid +flowchart TB + subgraph "(main.yml)" + A[step 1] + B["step 2 (defer: true)"] + C["step 3 (defer: true)"] + G[step 5] + end + + subgraph "step 4 (include.yml)" + D[included step 1] + E["included step 2 (defer: true)"] + F[included step 3] + end + + A --> D + D --> F + F --> G + G --> E + E --> C + C --> B +``` + +The step marked `defer` behaves as follows. + +- If `defer: true` is set, run of the step is deferred until finish of the runbook. +- Steps marked with `defer` are always run even if the running of intermediate steps fails. +- If there are multiple steps marked with `defer`, they are run in LIFO order. + - Also, the included steps are added to run sequence of the parent runbook's deferred steps.