Skip to content

Commit b8982a7

Browse files
doquanghuyclaude
andcommitted
docs(workflows): clarify continue_on_error scope — returned FAILED only
Copilot finding on d0b9e00: The README's "Error Handling" intro implied `continue_on_error` covers "any other runtime error raised during step execution", but the engine only consults the flag when a step returns `StepResult(status=FAILED, ...)`. Exceptions raised out of `step_impl.execute()` propagate to `WorkflowEngine.execute()`, where the catch-all logs `workflow_failed` and re-raises — the step result is never recorded, and the flag is never consulted. Audited the whole PR diff for the same overclaim: 1. workflows/README.md — main fix. Reworded the Error Handling intro to "any step that returns StepResult(status=FAILED, ...)" and promoted the parenthetical structural-validation note into the Notes block. Added a new "Scope: returned failures only" note that names the exception path explicitly and tells step authors how to bring the flag into scope for exceptional code (catch internally and return FAILED with the failure encoded in `output`). 2. tests/test_workflows.py — section comment used "when an executable step fails", same ambiguity. Tightened to "when a step returns StepResult(status=FAILED, ...)" and added a sentence calling out that unhandled exceptions are out of scope. 3. src/specify_cli/workflows/engine.py — already correct ("any step that returns FAILED" in the validator comment; "lets the pipeline route around the failure" in the execute path). No change. Engine semantics and test bodies are unchanged. Docs-only. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 22c5184 commit b8982a7

2 files changed

Lines changed: 27 additions & 17 deletions

File tree

‎tests/test_workflows.py‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2336,12 +2336,15 @@ def test_workflow_without_context_reference_unchanged(self, project_dir):
23362336
# ===== continue_on_error Tests =====
23372337
#
23382338
# Locks the contract documented in workflows/README.md "Error Handling"
2339-
# section: when an executable step fails and `continue_on_error: true`
2340-
# is declared, the engine records the step's `output` (with `exit_code`
2341-
# and `stderr` from the failure) and its `status` (sibling key on
2342-
# `steps.<id>`, not nested under `output`) and continues to the next
2343-
# sibling step instead of halting the run. Gate aborts
2344-
# (`output.aborted`) still halt regardless of the flag.
2339+
# section: when a step returns `StepResult(status=FAILED, ...)` and
2340+
# `continue_on_error: true` is declared, the engine records the step's
2341+
# `output` (with `exit_code` and `stderr` from the failure) and its
2342+
# `status` (sibling key on `steps.<id>`, not nested under `output`)
2343+
# and continues to the next sibling step instead of halting the run.
2344+
# Gate aborts (`output.aborted`) still halt regardless of the flag.
2345+
# Unhandled exceptions raised out of `step_impl.execute()` are out of
2346+
# scope for this flag — they propagate to `WorkflowEngine.execute()`
2347+
# and abort the run.
23452348

23462349

23472350
class TestContinueOnError:

‎workflows/README.md‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -221,17 +221,13 @@ Aggregate results from fan-out steps:
221221

222222
## Error Handling
223223

224-
By default, any step that ends in `StepStatus.FAILED` at runtime halts
225-
the entire run — most commonly a `shell` or `command` step exiting
226-
non-zero, but also any other runtime error raised during step
227-
execution. (Invalid workflow definitions are rejected up-front by
228-
`specify workflow run` before the run even starts, so structural
229-
validation failures never reach this code path.) Set
230-
`continue_on_error: true` on a step to record its result and continue
231-
to the next sibling step instead. When the failure was a non-zero
232-
exit, the exit code remains available on
233-
`steps.<id>.output.exit_code` so downstream `if`, `switch`, or `gate`
234-
steps can branch on it:
224+
By default, any step that returns `StepResult(status=FAILED, ...)`
225+
at runtime halts the entire run — most commonly a `shell` or
226+
`command` step exiting non-zero. Set `continue_on_error: true` on
227+
a step to record its result and continue to the next sibling step
228+
instead. When the failure was a non-zero exit, the exit code
229+
remains available on `steps.<id>.output.exit_code` so downstream
230+
`if`, `switch`, or `gate` steps can branch on it:
235231

236232
```yaml
237233
- id: heavy-thing
@@ -263,10 +259,21 @@ step in your own loop.
263259

264260
- The field must be a literal boolean (`true` / `false`); coerced
265261
strings like `"true"` are rejected at validation time.
262+
- **Scope: returned failures only.** The flag applies to step results
263+
with `status=FAILED`. Unhandled exceptions raised out of a step's
264+
`execute()` method are caught one level up by `WorkflowEngine.execute()`,
265+
logged as `workflow_failed`, and abort the run regardless of
266+
`continue_on_error`. If a step author wants the flag to cover an
267+
exceptional path, the step must catch the exception internally and
268+
return `StepResult(status=FAILED, ...)` with the failure encoded in
269+
`output` (e.g. `exit_code`, `stderr`, or a custom field).
266270
- Gate aborts (`on_reject: abort` chosen by the operator) always halt
267271
the run — `continue_on_error` does not override them. The flag is
268272
for transient/expected step failures, not for overriding deliberate
269273
operator decisions.
274+
- Structural validation runs up-front: `specify workflow run` rejects
275+
invalid workflow definitions before the run is created, so
276+
validation failures never reach this code path.
270277
- When the flag is omitted, behaviour is byte-equivalent to before
271278
this feature.
272279

0 commit comments

Comments
 (0)