Error-monad improvements
The error-monad is one of the oldest library of the tezos code base. It has evolved significantly since the start of the project (functorisation, abstraction, separation of the core part from the monad helpers from the extended stdlib additions, etc.). However, it still requires improvements.
This milestone aims to fix the main issues of the library. The main difficulties related to this milestone are to do with the pervasiveness of the library in the code base. It is used everywhere, including in the protocol, via modules in the different protocol-environments.
A kind of roadmap:
(Some parts are marked as - optional: Not a success criteria of the milestone, but likely to be tackled whilst working on the milestone. E.g., improvements that are one of the ways to enable another non-optional improvement, low-hanging fruits once another non-optional improvement is made, etc. - out-of-scope: Topically-related tasks that are beyond the objectives of the milestone. They'll only be tackled if there is enough time×personnel. Otherwise, issues will be opened for them with details plans formulated whilst working on this milestone.
The parts that are not marked as either are core parts of the milestone that form the success criteria.)
-
Define best practices: What do we want the error-management to look like in the future? This step is for refining all of the next step. It defines a direction that the error-management is meant to be moving towards. All the other steps are ways to move it, this one specifies the where.
There are already ideas about where we want things to go which should be integrated in a short list of bullet-point style guidelines. Not yet fully fledged documentation, but something that could grow to be documentation.
-
Modify the interface of the
error-monad
package to enable developers to follow the guidelines defined above. (I.e., give all the tools needed to follow the guidelines.) Modify the interface to discourage uses that fall outside of the guidelines. (#1582 (closed), #1581 (closed), #853, #1425 (closed), #1090) (and possibly out-of-scope additions: !2761 (closed)) -
Clean-up some legacy leftovers. This is intended to make the error-monad smaller and simpler.
- make traces abstract (requires some heavy refactoring for some parts of the code, e.g., micheline parsing) which is easier after step 1. (#1577)
- remove the classification system from the shell's error-monad but leave it for the protocol (follow-up for a different milestone in the future: consider changing the way classification of errors works in the protocol) (#1576)
- separate the core and monad part of the monad more cleanly (optional)
- push more of the (generic) monad within Lwtreslib (optional) and release Lwtreslib (optional, !3346 (merged) )
- move protocol env compatibility layer from envVX to structs (#1590) (optional)
- etc. (#1579 (closed), #905, #853)
-
Write extensive documentation (#905, #867 (closed), !2647 (closed))
- Formal documentation for all the interface of the error monad, whether new or old, whether trivial or complex
- Write a new tutorial for the error monad, something introductory that we can use as-is for on-boarding (possibly out-of-scope depending on personnel)
- Write guidelines and best-practices for error-management
- Write how-tos for common tasks (how to declare a new error, how to switch from one monad to another, how to wrap protocol errors into shell errors, etc.)
-
Rehaul error management in a "simple" component of the source-code (stdlib/stdlib_unix, or workers, or logging…) (possibly out-of-scope depending on personnel) (!2875 (closed))