structerr: Convert `New()` to return `Unknown` error codes

The `structerr.New()` constructor returns errors with an `Internal`
code. This makes for a somewhat weird interface though: `New()` shall be
used in cases where the actual error condition is not quite clear, but
by already setting an `Internal` error code we'll ultimately propagate
that code even if an ancestor in the callchain would know better.

Adjust the function to instead return `Unknown` errors. Together with
the change to always override `Unknown` errors with more specific ones,
this makes for a new calling convention of how to construct errors:
always use `New()`, unless you know the actual root cause. Like this,
the first caller that knows more about the root cause will override the
`Unknown` error.

Document this calling convention.

1 files changed, 5 insertions, 0 deletions

diff --git a/STYLE.md b/STYLE.md
index 7f6c8c70b..81132e77c 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -88,6 +88,11 @@ func CheckFrobnicated(s string) error {
 }
 ```
 
+Unless the root cause of an error can be determined and categorized, you should
+use `structerr.New()` to generate an error with an `Unknown` error code. This
+code will automatically get overridden when the error is wrapped with a specific
+error code.
+
 ### Error wrapping
 
 You should use wrapping directives `"%w"` to wrap errors. This