From 9625c589b0d3abb83b44e00e35d52050432a1b84 Mon Sep 17 00:00:00 2001
From: Lars Karlitski <lars@karlitski.net>
Date: Tue, 24 Mar 2020 23:33:54 +0100
Subject: [PATCH] docs: add errors.md

docs/errors.md are guidelines for how we handle errors. It's meant to be
expanded as we figure out more rules.
---
 docs/errors.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 docs/errors.md

diff --git a/docs/errors.md b/docs/errors.md
new file mode 100644
index 000000000..f9b952061
--- /dev/null
+++ b/docs/errors.md
@@ -0,0 +1,27 @@
+# Error Handling
+
+## When to Panic
+
+Always use `panic` for errors that can only happen when other code in
+*osbuild-composer* is wrong (also know as *programmer error*). This way, we
+catch these kinds of errors in unit tests while developing.
+
+Since only developers interact with these errors, a stacktrace including the
+error is all that's necessary. Don't include an additional message.
+
+For example, Go's `json.Marshal` can fail when receiving values that cannot be
+marshaled. However, when passing a known struct, we know it cannot fail:
+
+```golang
+bytes, err := json.Marshal();
+if err != nil {
+        panic(err)
+}
+```
+
+Some packages have functions prefixed with `Must`, which `panic()` on error.
+Use these when possible to save the error check:
+
+```golang
+re := regexp.MustCompile("v[0-9]")
+```