Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
41 lines
1.2 KiB
Markdown
41 lines
1.2 KiB
Markdown
# Error Handling — First Principles
|
|
|
|
## 1. The Principles
|
|
|
|
### P1. Errors are Data
|
|
Errors are structured, typed, and intentional. They are values, not
|
|
exceptions to the flow of code.
|
|
|
|
### P2. Fail Loudly
|
|
Never swallow an error. Silent failure is worse than visible failure.
|
|
|
|
### P3. Fail Specifically
|
|
Generic errors are debugging enemies. "Something went wrong" is
|
|
never acceptable.
|
|
|
|
### P4. Preserve Context
|
|
Errors carry where (file, line, function), when (timestamp, request),
|
|
why (cause), and what (user-facing message).
|
|
|
|
### P5. Recoverable When Possible
|
|
Retry, fallback, or degrade. Do not crash what can be salvaged.
|
|
|
|
### P6. Unrecoverable Means Stop
|
|
When recovery is impossible or unsafe, fail fast. Do not limp on
|
|
after fatal errors.
|
|
|
|
### P7. Errors are Boundaries
|
|
Define how errors cross API, service, and module boundaries. Translation
|
|
is explicit, not accidental.
|
|
|
|
### P8. User-Facing Errors are UX
|
|
Error messages are a feature. They are written for the user, not the
|
|
developer.
|
|
|
|
### P9. Errors are Logged
|
|
Even when handled, errors are recorded. The handling is the recovery;
|
|
the log is the memory.
|
|
|
|
### P10. Errors Don't Lie
|
|
Never catch what you cannot handle. Never claim success on failure.
|
|
Never claim failure on success. |