diff --git a/.spellcheck-en-custom.txt b/.spellcheck-en-custom.txt index 385f076..97145be 100644 --- a/.spellcheck-en-custom.txt +++ b/.spellcheck-en-custom.txt @@ -45,6 +45,7 @@ DCO Dependabot dev disambiguating +discoverability ditaa Docling docling @@ -227,6 +228,7 @@ specifiying splitter src Srivastava +SSL Staar Standup subcommand diff --git a/docs/adr-custom-exceptions.md b/docs/adr-custom-exceptions.md new file mode 100644 index 0000000..5f97a70 --- /dev/null +++ b/docs/adr-custom-exceptions.md @@ -0,0 +1,23 @@ +# InstructLab Custom Exceptions Pattern + +## Context + +The historically pervasive pattern for exception handling during application runtime is to catch internally raised exceptions in the CLI layer and use `click.secho` followed by `click.exceptions.Exit` to display a useful error message to the user before exiting the application. This leaves a risk of intermediate calls between the site of the exception and the user-facing layer changing, leading to missed new exceptions and outdated caught exceptions. A second issue is that of discoverability and verification: given a `click.exceptions.Exit` exception handling, it is not clear from the code where the caught exception originates from in the call stack, and, similarly, given a piece of code that can raise an exception, it is not clear from the local code whether that exception is properly handled in the CLI layer without investigation. + +These issues will compound whenever REST APIs begin development. + +## Decision + +InstructLab will adopt custom exceptions to handle specific faults which are then caught in the user-facing layer (CLI, REST API, &c). + +## Status + +Accepted + +## Consequences + +* Verification of exhaustive error handling will be clear within a code section that can raise. +* CLI layer error handling will be easy to understand and trace. +* Whenever REST APIs are developed, HTTP error codes should be easier to be associated with specific exceptions. +* It should be easier to compose useful error messages for the user. +* It should be easier to correctly scope exception handling (consider a `URLError` raised about SSL verification, for example, versus a custom `SSlVerificationException`).