From bfe00b656115ac0efd3dc2ef6ad69477751952ff Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 23 Jul 2020 12:04:40 -0700 Subject: [PATCH 1/7] Establish a new error handling project group --- text/0000-project-error-handling.md | 121 ++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) create mode 100644 text/0000-project-error-handling.md diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md new file mode 100644 index 00000000000..67e4ead0bbf --- /dev/null +++ b/text/0000-project-error-handling.md @@ -0,0 +1,121 @@ +- Feature Name: error_handling_project_group +- Start Date: 2020-07-23 +- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) +- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) + +# Summary +[summary]: #summary + +This RFC establishes a new project group, under the libs team, to drive efforts to improve error handling in Rust. + +# Motivation +[motivation]: #motivation + +The error handling project group aims to reduce confusion on how to structure error handling for users in the rust community. This will be accomplished by creating learning resources and pushing effort to upstream widely used crates into std. As a secondary goal this project group will also try to resolve some known issues with the Error trait and reporting errors in panics/termination. + +# Charter +[charter]: #charter + +## Goals + +### Agree on and define common error handling terminology + +- Recoverable error: An error that can reasonably be expected to be encountered e.g. a missing file. +- Unrecoverable error: An error that cannot reasonably be expected to happen and which indicates a bug e.g. indexing out of bounds. +- 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. +- Reporting Type: A type that can store all recoverable errors an application may need to propogate and print them as error reports. + - Reporting types can represent the recoverable errors either via concrete types, likely paramaterized, or trait objects. + - Reporting types often bundle context with errors when they are constructed, e.g. `Backtrace`. + - 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`. + +### Come to a consensus on current best practices + +Here is a tenative starting point, subject to change: + +- Use `Result` and `Error` types for recoverable errors. +- Use `panic` for unrecoverable errors. +- Impl `Error` for error types that may need to be reported to a human or be composed with other errors. +- Use enums for types representing multiple failure cases that may need to be handled. + - For libraries, oftentimes you want to support both reporting and handling so you impl `Error` on a possibly non-exhaustive enum. +- Error kind pattern for associating context with every enum variant without including the member in every enum variant. +- 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. +- Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s. +- What is the concensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` impl Error? + + +### Communicate current best practices + +- Document the concensus. +- Communicate plan for future changes to error handling, and the libraries that future changes are being based off of. +- Produce learning resources related to current best practices. + - New chapters in the book? + +### Evaluate options for error reporting type aka better `Box` + +- Survey the current libraries in the ecosystem: + - `anyhow` + - `eyre` +- Evaluate value of features including: + - Single word width on stack + - Error wrapping with display types and with special downcast support. + - report hook + configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors. + - libcore compatibility. + +### Consolidate ecosystem by merging best practice crates into std + +- Provide a derive macro for `Error` in std. +- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the Error trait. + - Provide necessary API on `Backtrace` to support crates like `color-backtrace`. +- Move error to core . + - Depends on generic member access. + - Requires resolving downcast dependency on `Box` and blocking the stabilization of `fn backtrace`. +- Potentially stabilize an error Reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets. + +### Add missing features + +- Generic member access on the `Error` trait. +- `Error` return traces: + - Depends on specialization and generic member access. +- Fix rough corners around reporting errors and `Termination`. + +## Non Goals + +- This group should not be involved in design discussions for the `Try` trait, `try` blocks, or `try` fns. + +## Membership Requirements + +- Group membership is open, any interested party can participate in discussions, repeat contributors will be added appropriate teams. + +## Additional Questions + +### What support do you need, and separately want, from the Rust organization? + +I'm not sure, my main concern is getting prompt feedback on RFCs. + +### Why should this be a project group over a community effort? + +Error handling has historically been handled via community effort which has resulted a great deal of competing and outdated solutions and resources. An officially supported project group has the best chance of writing and maintaining up-to-date resources that would reach a wide audience. + +### What do you expect the relationship to the team be? + +The project group will create RFCs for various changes to the standard library and the team will review them via the standard RFC process. + +### Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.) + +Jane Lusby, Andrew Gallant, and Sean Chen. + +### Is your group long-running or temporary? + +Temporary. + +### If it is temporary, how long do you see it running for? + +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. + +### If applicable, which other groups or teams do you expect to have close contact with? + +Primarily the libs team, but there may be some small interactions with the lang team, compiler team, and traits working group. + +### Where do you see your group needing help? + +Primarily in drafting RFCs, writing is not this author's strong suit. \ No newline at end of file From 5bfa0465733b4296c68311c34409451c0cf0c3d1 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Sun, 26 Jul 2020 10:39:28 -0700 Subject: [PATCH 2/7] Update text/0000-project-error-handling.md --- text/0000-project-error-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md index 67e4ead0bbf..5e320d0c7b9 100644 --- a/text/0000-project-error-handling.md +++ b/text/0000-project-error-handling.md @@ -40,7 +40,7 @@ Here is a tenative starting point, subject to change: - Error kind pattern for associating context with every enum variant without including the member in every enum variant. - 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. - Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s. -- What is the concensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` impl Error? +- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` impl Error? ### Communicate current best practices @@ -118,4 +118,4 @@ Primarily the libs team, but there may be some small interactions with the lang ### Where do you see your group needing help? -Primarily in drafting RFCs, writing is not this author's strong suit. \ No newline at end of file +Primarily in drafting RFCs, writing is not this author's strong suit. From d12f66a8b51ed2d0262641bdfaee92de75214787 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 27 Jul 2020 18:06:35 -0700 Subject: [PATCH 3/7] Apply suggestions from code review Co-authored-by: Jake Goulding --- text/0000-project-error-handling.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md index 5e320d0c7b9..146b94fa880 100644 --- a/text/0000-project-error-handling.md +++ b/text/0000-project-error-handling.md @@ -11,7 +11,7 @@ This RFC establishes a new project group, under the libs team, to drive efforts # Motivation [motivation]: #motivation -The error handling project group aims to reduce confusion on how to structure error handling for users in the rust community. This will be accomplished by creating learning resources and pushing effort to upstream widely used crates into std. As a secondary goal this project group will also try to resolve some known issues with the Error trait and reporting errors in panics/termination. +The error handling project group aims to reduce confusion on how to structure error handling for users in the Rust community. This will be accomplished by creating learning resources and pushing effort to upstream widely used crates into the standard library. As a secondary goal, this project group will also try to resolve some known issues with the `Error` trait and reporting errors in panics/termination. # Charter [charter]: #charter @@ -22,9 +22,9 @@ The error handling project group aims to reduce confusion on how to structure er - Recoverable error: An error that can reasonably be expected to be encountered e.g. a missing file. - Unrecoverable error: An error that cannot reasonably be expected to happen and which indicates a bug e.g. indexing out of bounds. -- 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. -- Reporting Type: A type that can store all recoverable errors an application may need to propogate and print them as error reports. - - Reporting types can represent the recoverable errors either via concrete types, likely paramaterized, or trait objects. +- 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. +- Reporting Type: A type that can store all recoverable errors an application may need to propagate and print them as error reports. + - Reporting types can represent the recoverable errors either via concrete types, likely parameterized, or trait objects. - Reporting types often bundle context with errors when they are constructed, e.g. `Backtrace`. - 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`. @@ -34,23 +34,23 @@ Here is a tenative starting point, subject to change: - Use `Result` and `Error` types for recoverable errors. - Use `panic` for unrecoverable errors. -- Impl `Error` for error types that may need to be reported to a human or be composed with other errors. +- Implement `Error` for error types that may need to be reported to a human or be composed with other errors. - Use enums for types representing multiple failure cases that may need to be handled. - - For libraries, oftentimes you want to support both reporting and handling so you impl `Error` on a possibly non-exhaustive enum. + - For libraries, oftentimes you want to support both reporting and handling so you implement `Error` on a possibly non-exhaustive enum. - Error kind pattern for associating context with every enum variant without including the member in every enum variant. - 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. - Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s. -- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` impl Error? +- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` implement `Error`? ### Communicate current best practices -- Document the concensus. +- Document the consensus. - Communicate plan for future changes to error handling, and the libraries that future changes are being based off of. - Produce learning resources related to current best practices. - New chapters in the book? -### Evaluate options for error reporting type aka better `Box` +### Evaluate options for error reporting type a.k.a. better `Box` - Survey the current libraries in the ecosystem: - `anyhow` @@ -58,18 +58,18 @@ Here is a tenative starting point, subject to change: - Evaluate value of features including: - Single word width on stack - Error wrapping with display types and with special downcast support. - - report hook + configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors. + - Report hook and configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors. - libcore compatibility. ### Consolidate ecosystem by merging best practice crates into std - Provide a derive macro for `Error` in std. -- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the Error trait. +- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the `Error` trait. - Provide necessary API on `Backtrace` to support crates like `color-backtrace`. -- Move error to core . +- Move `Error` to core. - Depends on generic member access. - Requires resolving downcast dependency on `Box` and blocking the stabilization of `fn backtrace`. -- Potentially stabilize an error Reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets. +- Potentially stabilize an error reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets. ### Add missing features @@ -84,7 +84,7 @@ Here is a tenative starting point, subject to change: ## Membership Requirements -- Group membership is open, any interested party can participate in discussions, repeat contributors will be added appropriate teams. +- Group membership is open, any interested party can participate in discussions, repeat contributors will be added to appropriate teams. ## Additional Questions From c9804b17134b94917b9a7a8a5dd6c77289fc029c Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 27 Jul 2020 18:45:53 -0700 Subject: [PATCH 4/7] update justification for project group --- text/0000-project-error-handling.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md index 146b94fa880..85047d49a5b 100644 --- a/text/0000-project-error-handling.md +++ b/text/0000-project-error-handling.md @@ -94,7 +94,16 @@ I'm not sure, my main concern is getting prompt feedback on RFCs. ### Why should this be a project group over a community effort? -Error handling has historically been handled via community effort which has resulted a great deal of competing and outdated solutions and resources. An officially supported project group has the best chance of writing and maintaining up-to-date resources that would reach a wide audience. +There isn't anything in this project group that can't be handled as a +community effort, but centralizing work into a project group should help +speed things. Error handling is a core aspect of the language and changes in +error handling have large impacts on the ecosystem. Ensuring that efforts to +refine error handling within Rust have sufficient resources and don't stall +out is in the best interests of the community. By organizing efforts as a +project group we will hopefully have an easier time recruiting new members, +getting attention on RFCs from members of the libs team, and using the +established resources and expertise of the rust organization for coordinating +our efforts. ### What do you expect the relationship to the team be? From 508f438ebeb64e5f343db1039c08fd01bea82e83 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 28 Jul 2020 10:28:56 -0700 Subject: [PATCH 5/7] add section on identifying areas needing improvment --- text/0000-project-error-handling.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md index 85047d49a5b..e3d7ad61ad2 100644 --- a/text/0000-project-error-handling.md +++ b/text/0000-project-error-handling.md @@ -43,6 +43,13 @@ Here is a tenative starting point, subject to change: - What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` implement `Error`? +### Identify pain points in error handling today + +- Backtrace capture is expensive, but without one it can be difficult to pinpoint the origin of errors +- unwrap on errors without first converting to a reporting type will often discard relevant information +- errors printing from main have to assume a prefixed `Error: `, sub par control of output format when printing during termination. +- Error trait only exposes 3 forms of context, can only represent singly linked lists for chains of errors + ### Communicate current best practices - Document the consensus. From 23e262d94b2ab18b7f30188ef925c5c308459bee Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 30 Jul 2020 16:47:48 -0700 Subject: [PATCH 6/7] more updates from code review --- text/0000-project-error-handling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md index e3d7ad61ad2..e2654404d1f 100644 --- a/text/0000-project-error-handling.md +++ b/text/0000-project-error-handling.md @@ -20,8 +20,8 @@ The error handling project group aims to reduce confusion on how to structure er ### Agree on and define common error handling terminology -- Recoverable error: An error that can reasonably be expected to be encountered e.g. a missing file. -- Unrecoverable error: An error that cannot reasonably be expected to happen and which indicates a bug e.g. indexing out of bounds. +- Recoverable error: An error that can be reacted and recovered from when encountered e.g. a missing file. +- Unrecoverable error: An error that cannot reasonably be reacted to or recovered from and which indicates a bug e.g. indexing out of bounds. - 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. - Reporting Type: A type that can store all recoverable errors an application may need to propagate and print them as error reports. - Reporting types can represent the recoverable errors either via concrete types, likely parameterized, or trait objects. @@ -118,7 +118,7 @@ The project group will create RFCs for various changes to the standard library a ### Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.) -Jane Lusby, Andrew Gallant, and Sean Chen. +Jane Lusby(@yaahc_), Andrew Gallant(@BurntSushi), and Sean Chen(@seanchen1991). ### Is your group long-running or temporary? From e3e1a36c4aede064013b212d41b964c65944bb79 Mon Sep 17 00:00:00 2001 From: Amanieu d'Antras Date: Fri, 18 Sep 2020 16:10:12 +0100 Subject: [PATCH 7/7] RFC 2965 is "Establish a new error handling project group" --- text/0000-project-error-handling.md | 137 ---------------------------- 1 file changed, 137 deletions(-) delete mode 100644 text/0000-project-error-handling.md diff --git a/text/0000-project-error-handling.md b/text/0000-project-error-handling.md deleted file mode 100644 index e2654404d1f..00000000000 --- a/text/0000-project-error-handling.md +++ /dev/null @@ -1,137 +0,0 @@ -- Feature Name: error_handling_project_group -- Start Date: 2020-07-23 -- RFC PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) -- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) - -# Summary -[summary]: #summary - -This RFC establishes a new project group, under the libs team, to drive efforts to improve error handling in Rust. - -# Motivation -[motivation]: #motivation - -The error handling project group aims to reduce confusion on how to structure error handling for users in the Rust community. This will be accomplished by creating learning resources and pushing effort to upstream widely used crates into the standard library. As a secondary goal, this project group will also try to resolve some known issues with the `Error` trait and reporting errors in panics/termination. - -# Charter -[charter]: #charter - -## Goals - -### Agree on and define common error handling terminology - -- Recoverable error: An error that can be reacted and recovered from when encountered e.g. a missing file. -- Unrecoverable error: An error that cannot reasonably be reacted to or recovered from and which indicates a bug e.g. indexing out of bounds. -- 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. -- Reporting Type: A type that can store all recoverable errors an application may need to propagate and print them as error reports. - - Reporting types can represent the recoverable errors either via concrete types, likely parameterized, or trait objects. - - Reporting types often bundle context with errors when they are constructed, e.g. `Backtrace`. - - 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`. - -### Come to a consensus on current best practices - -Here is a tenative starting point, subject to change: - -- Use `Result` and `Error` types for recoverable errors. -- Use `panic` for unrecoverable errors. -- Implement `Error` for error types that may need to be reported to a human or be composed with other errors. -- Use enums for types representing multiple failure cases that may need to be handled. - - For libraries, oftentimes you want to support both reporting and handling so you implement `Error` on a possibly non-exhaustive enum. -- Error kind pattern for associating context with every enum variant without including the member in every enum variant. -- 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. -- Recommend `Box`ing concrete error types when stack size is an issue rather than `Box`ing and converting to `dyn Error`s. -- What is the consensus on handling `dyn Error`s? Should it be encouraged or discouraged? Should we look into making `Box` implement `Error`? - - -### Identify pain points in error handling today - -- Backtrace capture is expensive, but without one it can be difficult to pinpoint the origin of errors -- unwrap on errors without first converting to a reporting type will often discard relevant information -- errors printing from main have to assume a prefixed `Error: `, sub par control of output format when printing during termination. -- Error trait only exposes 3 forms of context, can only represent singly linked lists for chains of errors - -### Communicate current best practices - -- Document the consensus. -- Communicate plan for future changes to error handling, and the libraries that future changes are being based off of. -- Produce learning resources related to current best practices. - - New chapters in the book? - -### Evaluate options for error reporting type a.k.a. better `Box` - -- Survey the current libraries in the ecosystem: - - `anyhow` - - `eyre` -- Evaluate value of features including: - - Single word width on stack - - Error wrapping with display types and with special downcast support. - - Report hook and configurable `dyn ReportHandler` type for custom report formats and content, similar to panic handler but for errors. - - libcore compatibility. - -### Consolidate ecosystem by merging best practice crates into std - -- Provide a derive macro for `Error` in std. -- Stabilize the `Backtrace` type but possibly not `fn backtrace` on the `Error` trait. - - Provide necessary API on `Backtrace` to support crates like `color-backtrace`. -- Move `Error` to core. - - Depends on generic member access. - - Requires resolving downcast dependency on `Box` and blocking the stabilization of `fn backtrace`. -- Potentially stabilize an error reporting type based on `anyhow` and `eyre` now that they're close to having identical feature sets. - -### Add missing features - -- Generic member access on the `Error` trait. -- `Error` return traces: - - Depends on specialization and generic member access. -- Fix rough corners around reporting errors and `Termination`. - -## Non Goals - -- This group should not be involved in design discussions for the `Try` trait, `try` blocks, or `try` fns. - -## Membership Requirements - -- Group membership is open, any interested party can participate in discussions, repeat contributors will be added to appropriate teams. - -## Additional Questions - -### What support do you need, and separately want, from the Rust organization? - -I'm not sure, my main concern is getting prompt feedback on RFCs. - -### Why should this be a project group over a community effort? - -There isn't anything in this project group that can't be handled as a -community effort, but centralizing work into a project group should help -speed things. Error handling is a core aspect of the language and changes in -error handling have large impacts on the ecosystem. Ensuring that efforts to -refine error handling within Rust have sufficient resources and don't stall -out is in the best interests of the community. By organizing efforts as a -project group we will hopefully have an easier time recruiting new members, -getting attention on RFCs from members of the libs team, and using the -established resources and expertise of the rust organization for coordinating -our efforts. - -### What do you expect the relationship to the team be? - -The project group will create RFCs for various changes to the standard library and the team will review them via the standard RFC process. - -### Who are the initial shepherds/leaders? (This is preferably 2–3 individuals, but not required.) - -Jane Lusby(@yaahc_), Andrew Gallant(@BurntSushi), and Sean Chen(@seanchen1991). - -### Is your group long-running or temporary? - -Temporary. - -### If it is temporary, how long do you see it running for? - -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. - -### If applicable, which other groups or teams do you expect to have close contact with? - -Primarily the libs team, but there may be some small interactions with the lang team, compiler team, and traits working group. - -### Where do you see your group needing help? - -Primarily in drafting RFCs, writing is not this author's strong suit.