Merge pull request #834 from trezor/tsusanka/docs-exceptions

Docs: add info about exceptions usage

docs/SUMMARY.md

@@ -8,6 +8,9 @@
   - [Emulator](core/emulator/index.md)
   - [Apps](core/src/apps.md)
   - [Tests](core/tests/index.md)
+  - [Miscellaneous](core/misc/index.md)
+    - [SLIP-39](core/misc/slip0039.md)
+    - [Exceptions usage](core/misc/exceptions.md)
 - [Legacy](legacy/index.md)
 - [Python](python/index.md)
   - [trezorlib](python/trezorlib.md)

docs/core/misc/exceptions.md

@@ -0,0 +1,36 @@
+# Exceptions in Core
+
+From version 2.3.0 we try to follow few rules about how we use exceptions. All new
+code MUST follow these.
+
+## Usage
+
+You MAY use any exceptions in Core's logic. Exceptions from `wire.errors` SHOULD be
+the final exceptions that are thrown and SHOULD NOT be caught. Note that `wire.Error`
+is a type of exception that is intended to be sent out over the wire. It should only
+be used in contexts where that behavior is appropriate.
+
+Custom exception type hierarchies SHOULD always be derived directly from Exception.
+They SHOULD NOT be derived from other built-in exceptions (such as ValueError,
+TypeError, etc.)
+
+Deriving a custom exception type signals an intention to catch and handle it
+somewhere in the code. For this reason, custom exception types SHOULD NOT be derived
+from wire.Error and subclasses.
+
+Exception strings, including in internal exceptions, SHOULD only be used in cases
+where the text is intended to be shown on the host. Exception strings MUST NOT
+contain any sensitive information. An explanation of an internal exception MAY be
+placed as a comment on the raise statement, to aid debugging. If an exception is
+thrown with no arguments, the exception class SHOULD be thrown instead of a new
+object, i.e., `raise CustomError` instead of `raise CustomError()`.
+
+## Tl;dr
+
+- Do not use `wire.errors` for `try-catch` statements, use other exceptions.
+- Use `wire.errors` solely as a way to communicate errors to the Host, do not include
+them somewhere deep in the stack.
+- Do not put sensitive information in exception's message. If you are not sure, do not
+add any message and provide a comment next to the `raise` statement.
+- Use `raise CustomError` instead of `raise CustomError()` if you are omitting the
+exception message.

docs/core/misc/index.md

@@ -1 +1,6 @@
 # Miscellaneous
+
+Topics that do not fit elsewhere:
+
+- [SLIP-39 in Core](core/misc/slip0039.md)
+- [Exceptions usage](core/misc/exceptions.md)

docs/index.md

@@ -30,3 +30,8 @@ Also please have a look at the docs, either in the `docs` folder or at  [docs.tr
 ## Security vulnerability disclosure
 
 Please report suspected security vulnerabilities in private to [security@satoshilabs.com](mailto:security@satoshilabs.com), also see [the disclosure section on the Trezor.io website](https://trezor.io/security/). Please do NOT create publicly viewable issues for suspected security vulnerabilities.
+
+## Note on terminology
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
+"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).