|
1 | | -# {{GROUP_NAME}} Charter |
2 | | -<!-- |
3 | | - Provide an introduction summarising the goals and motivation behind your |
4 | | - project group. |
5 | | ---> |
| 1 | +# Charter |
| 2 | +[charter]: #charter |
6 | 3 |
|
7 | 4 | ## Goals |
8 | 5 |
|
9 | | -<!-- |
10 | | - Explain what changes you'd like to see your group your group to focus on, and |
11 | | - how you plan to approach these issues. Focus on explaining the highest possible |
12 | | - level of your change. |
13 | | ---> |
| 6 | +### Agree on and define common error handling terminology |
14 | 7 |
|
15 | | -## Constraints And Considerations |
| 8 | +- Recoverable error: An error that can be reacted and recovered from when encountered e.g. a missing file. |
| 9 | +- Unrecoverable error: An error that cannot reasonably be reacted to or recovered from and which indicates a bug e.g. indexing out of bounds. |
| 10 | +- Error Type: A type that represents a recoverable error. Error types can optionally implement the `Error` trait so that it can be reported to the user or be converted into a trait object. |
| 11 | +- Reporting Type: A type that can store all recoverable errors an application may need to propagate and print them as error reports. |
| 12 | + - Reporting types can represent the recoverable errors either via concrete types, likely parameterized, or trait objects. |
| 13 | + - Reporting types often bundle context with errors when they are constructed, e.g. `Backtrace`. |
| 14 | + - Reporting types often provide helper functions for creating ad hoc errors whose only purpose is to be reported e.g. `anyhow::format_err!` or `eyre::WrapErr`. |
16 | 15 |
|
17 | | -<!-- |
18 | | - Explain the scope of your group, what you have chosen not to include in |
19 | | - your goals, and your motivations behind making them non-goals. |
20 | | ---> |
| 16 | +### Come to a consensus on current best practices |
21 | 17 |
|
| 18 | +Here is a tenative starting point, subject to change: |
22 | 19 |
|
23 | | -## Membership |
| 20 | +- Use `Result` and `Error` types for recoverable errors. |
| 21 | +- Use `panic` for unrecoverable errors. |
| 22 | +- Implement `Error` for error types that may need to be reported to a human or be composed with other errors. |
| 23 | +- Use enums for types representing multiple failure cases that may need to be handled. |
| 24 | + - For libraries, oftentimes you want to support both reporting and handling so you implement `Error` on a possibly non-exhaustive enum. |
| 25 | +- Error kind pattern for associating context with every enum variant without including the member in every enum variant. |
| 26 | +- Convert to a reporting type when the error is no longer expected to be handled beyond reporting e.g. `anyhow::Error` or `eyre::Report` or when trait object + downcast error handling is preferable. |
| 27 | +- Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s. |
| 28 | +- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box<dyn Error...>` implement `Error`? |
24 | 29 |
|
25 | | -<!-- |
26 | | - Mention your initial membership and who has decided take the roles of |
27 | | - shepherd(s) and liason. |
28 | | ---> |
29 | 30 |
|
30 | | -**Shepherd:** |
31 | | -**Team Liason:** |
32 | | -**Members:** |
| 31 | +### Identify pain points in error handling today |
| 32 | + |
| 33 | +- Backtrace capture is expensive, but without it can be difficult to pinpoint the origin of errors |
| 34 | +- unwrapping errors without first converting to a reporting type will often discard relevant information |
| 35 | +- errors printed from `main` have to assume a prefixed `Error: `, sub-par control of output format when printing during termination. |
| 36 | +- The `Error` trait only exposes three forms of context, can only represent singly-linked lists for chains of errors |
| 37 | + |
| 38 | +### Communicate current best practices |
| 39 | + |
| 40 | +- Document the consensus. |
| 41 | +- Communicate plan for future changes to error handling, and the libraries that future changes are being based off of. |
| 42 | +- Produce learning resources related to current best practices. |
| 43 | + - New chapters in the book? |
| 44 | + |
| 45 | +### Evaluate options for error reporting type a.k.a. better `Box<dyn Error>` |
| 46 | + |
| 47 | +- Survey the current libraries in the ecosystem: |
| 48 | + - `anyhow` |
| 49 | + - `eyre` |
| 50 | +- Evaluate value of features including: |
| 51 | + - Single word width on stack |
| 52 | + - Error wrapping with display types and with special downcast support. |
| 53 | + - Report hook and configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors. |
| 54 | + - `#[no_std]` support |
| 55 | + |
| 56 | +### Consolidate ecosystem by merging best practice crates into std |
| 57 | + |
| 58 | +- Provide a derive macro for `Error` in std. |
| 59 | +- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the `Error` trait. |
| 60 | + - Provide necessary API on `Backtrace` to support crates like `color-backtrace`. |
| 61 | +- Move `Error` to core. |
| 62 | + - Depends on generic member access. |
| 63 | + - Requires resolving downcast dependency on `Box` and blocking the stabilization of `fn backtrace`. |
| 64 | +- Potentially stabilize an error reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets. |
| 65 | + |
| 66 | +### Add missing features |
| 67 | + |
| 68 | +- Generic member access on the `Error` trait. |
| 69 | +- `Error` return traces: |
| 70 | + - Depends on specialization and generic member access. |
| 71 | +- Fix rough corners around reporting errors and `Termination`. |
| 72 | + |
| 73 | +## Non Goals |
| 74 | + |
| 75 | +- This group should not be involved in managing design discussions for the `Try` trait, `try` blocks, or `try` fns. |
| 76 | + |
| 77 | +## Membership Requirements |
| 78 | + |
| 79 | +- Group membership is open, any interested party can participate in discussions, repeat contributors will be added to appropriate teams. |
| 80 | + |
| 81 | +## Additional Questions |
| 82 | + |
| 83 | +### What support do you need, and separately want, from the Rust organization? |
| 84 | + |
| 85 | +I'm not sure, my main concern is getting prompt feedback on RFCs. |
| 86 | + |
| 87 | +### Why should this be a project group over a community effort? |
| 88 | + |
| 89 | +There isn't anything in this project group that can't be handled as a |
| 90 | +community effort, but centralizing work into a project group should help |
| 91 | +speed things. Error handling is a core aspect of the language and changes in |
| 92 | +error handling have large impacts on the ecosystem. Ensuring that efforts to |
| 93 | +refine error handling within Rust have sufficient resources and don't stall |
| 94 | +out is in the best interests of the community. By organizing efforts as a |
| 95 | +project group we will hopefully have an easier time recruiting new members, |
| 96 | +getting attention on RFCs from members of the libs team, and using the |
| 97 | +established resources and expertise of the rust organization for coordinating |
| 98 | +our efforts. |
| 99 | + |
| 100 | +### What do you expect the relationship to the team be? |
| 101 | + |
| 102 | +The project group will create RFCs for various changes to the standard library and the team will review them via the standard RFC process. |
| 103 | + |
| 104 | +### Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.) |
| 105 | + |
| 106 | +Jane Lusby(@yaahc), Andrew Gallant(@BurntSushi), and Sean Chen(@seanchen1991). |
| 107 | + |
| 108 | +### Is your group long-running or temporary? |
| 109 | + |
| 110 | +Temporary. |
| 111 | + |
| 112 | +### If it is temporary, how long do you see it running for? |
| 113 | + |
| 114 | +This depends pretty heavily on how quickly the RFCs move, anywhere between 6 months and 2 years I'd guess but don't quote me on this. |
| 115 | + |
| 116 | +### If applicable, which other groups or teams do you expect to have close contact with? |
| 117 | + |
| 118 | +Primarily the libs team, but there may be some small interactions with the lang team, compiler team, and traits working group. |
| 119 | + |
| 120 | +### Where do you see your group needing help? |
| 121 | + |
| 122 | +Primarily in drafting RFCs, writing is not this author's strong suit. |
0 commit comments