From ae0dbe0a58e8a46c655e5a6ac630ce0437923e2a Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 15:47:17 -0500 Subject: [PATCH 01/11] Fill in README --- CHARTER.md | 136 ++++++++++++++++++++++++++++++++++++++++++++--------- README.md | 83 +++++--------------------------- 2 files changed, 126 insertions(+), 93 deletions(-) diff --git a/CHARTER.md b/CHARTER.md index e0b3180..26559ef 100644 --- a/CHARTER.md +++ b/CHARTER.md @@ -1,32 +1,122 @@ -# {{GROUP_NAME}} Charter - +# Charter +[charter]: #charter ## Goals - +### Agree on and define common error handling terminology -## Constraints And Considerations +- 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: -## Membership +- 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`? - -**Shepherd:** -**Team Liason:** -**Members:** +### Identify pain points in error handling today + +- Backtrace capture is expensive, but without it can be difficult to pinpoint the origin of errors +- unwrapping errors without first converting to a reporting type will often discard relevant information +- errors printed from `main` have to assume a prefixed `Error: `, sub-par control of output format when printing during termination. +- The `Error` trait only exposes three 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. + - `#[no_std]` support + +### 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 managing 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. \ No newline at end of file diff --git a/README.md b/README.md index 62d1ff8..64c87e9 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,26 @@ -# {{GROUP_NAME}} {{GROUP_TYPE}} Group - - - -![project group status: active](https://img.shields.io/badge/status-active-brightgreen.svg) -[![project group documentation](https://img.shields.io/badge/MDBook-View%20Documentation-blue)][gh-pages] - - -**FIX ME** - - - -Welcome the repository for the {{GROUP_NAME}} Project Group! This is the -repository we use to organise our work. Please refer to our [charter] as well -as our [github pages website][gh-pages] for more information on our goals and +This is the repository we use to organise our work. Please refer to our [charter] for more information on our goals and current scope. -[charter]: ./CHARTER.md -[gh-pages]: https://rust-lang.github.io/{{GROUP_SLUG}} - -**/FIX ME** + - Shepherd: + - [yaahc](https://github.com/yaahc) + - [seanchen1991](https://github.com/seanchen1991) + - Rust library team contact: + - [BurntSushi](https://github.com/burntsushi) +[charter]: ./CHARTER.md ## How Can I Get Involved? -**FIX ME** - - - -[You can find a list of the current members available -on `rust-lang/team`.][team-toml] - -If you'd like to participate be sure to check out any of our [open issues] on this -repository. - -We also participate on [{{CHAT_PLATFORM}}][chat-link], feel free to introduce -yourself over there and ask us any questions you have. +If you'd like to participate be sure to check out any of our [open issues] on this repository. +We also participate on [Zulip][chat-link], feel free to introduce yourself over there and ask us any questions you have. [open issues]: /issues -[chat-link]: {{CHAT_LINK}} +[chat-link]: https://rust-lang.zulipchat.com/#narrow/stream/257204-project-error-handling [team-toml]: https://github.com/rust-lang/team/blob/master/teams/{{GROUP_TYPE}}-{{GROUP_SLUG}}.toml -**/FIX ME** - -## Building Documentation -This repository is also an mdbook project. You can view and build it using the -following command. - -``` -mdbook serve -``` From e2d0904b690aa02bb53f7eff0355572ad3f5f336 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 15:51:04 -0500 Subject: [PATCH 02/11] Remove unused files --- README.md | 6 +++--- SUMMARY.md | 6 ------ book.toml | 10 ---------- 3 files changed, 3 insertions(+), 19 deletions(-) delete mode 100644 SUMMARY.md delete mode 100644 book.toml diff --git a/README.md b/README.md index 64c87e9..b018a9d 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,10 @@ This is the repository we use to organise our work. Please refer to our [charter current scope. - Shepherd: - - [yaahc](https://github.com/yaahc) - - [seanchen1991](https://github.com/seanchen1991) + - [Jane Lusby (yaahc)](https://github.com/yaahc) + - [Sean Chen (seanchen1991)](https://github.com/seanchen1991) - Rust library team contact: - - [BurntSushi](https://github.com/burntsushi) + - [Andrew Gallant (BurntSushi)](https://github.com/burntsushi) [charter]: ./CHARTER.md diff --git a/SUMMARY.md b/SUMMARY.md deleted file mode 100644 index 3c3c5a7..0000000 --- a/SUMMARY.md +++ /dev/null @@ -1,6 +0,0 @@ -# Summary - -- [Welcome](./README.md) -- [Charter](./CHARTER.md) -- [Meetings](./meetings/README.md) -- [Draft RFCs](./draft-rfcs/README.md) diff --git a/book.toml b/book.toml deleted file mode 100644 index 93b82ea..0000000 --- a/book.toml +++ /dev/null @@ -1,10 +0,0 @@ -[book] -authors = ["{{GROUP_NAME}} Members"] -language = "en" -multilingual = false -src = "." -title = "{{GROUP_NAME}} {{GROUP_TYPE}} Group" - -[output.html] -no-section-label=true -git-repository-url="https://github.com/rust-lang/{{GROUP_SLUG}}" From d2e20f58ff9df9cab51d7d43146c7b43fb9aece3 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 15:57:04 -0500 Subject: [PATCH 03/11] Fix a typo --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index b018a9d..6998dc1 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # Error Handling Project Group -Welcome the repository for the Error Handling Project Group! We're focused on -defining and communicating Rust's error handling story. +Welcome to the repository for the Error Handling Project Group! We're focused on defining and communicating Rust's error handling story. This is the repository we use to organise our work. Please refer to our [charter] for more information on our goals and current scope. From e4737e447f593e4feb5a65b13854f88867b2bfd2 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:08:45 -0500 Subject: [PATCH 04/11] Update README.md Co-authored-by: Jane Lusby --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 6998dc1..caa6f9e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Error Handling Project Group -Welcome to the repository for the Error Handling Project Group! We're focused on defining and communicating Rust's error handling story. +Welcome to the repository for the Error Handling Project Group! We're focused on defining and communicating Rust's error handling story. This is the repository we use to organise our work. Please refer to our [charter] for more information on our goals and current scope. @@ -22,4 +22,3 @@ We also participate on [Zulip][chat-link], feel free to introduce yourself over [open issues]: /issues [chat-link]: https://rust-lang.zulipchat.com/#narrow/stream/257204-project-error-handling [team-toml]: https://github.com/rust-lang/team/blob/master/teams/{{GROUP_TYPE}}-{{GROUP_SLUG}}.toml - From d067458b1663c9ef01e7453cf083b769da4522f6 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:14:35 -0500 Subject: [PATCH 05/11] Add back summary and book.toml --- SUMMARY.md | 6 ++++++ book.toml | 10 ++++++++++ 2 files changed, 16 insertions(+) create mode 100644 SUMMARY.md create mode 100644 book.toml diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 0000000..3c3c5a7 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,6 @@ +# Summary + +- [Welcome](./README.md) +- [Charter](./CHARTER.md) +- [Meetings](./meetings/README.md) +- [Draft RFCs](./draft-rfcs/README.md) diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..81f82c7 --- /dev/null +++ b/book.toml @@ -0,0 +1,10 @@ +[book] +authors = ["{{GROUP_NAME}}] Members"] +language = "en" +multilingual = false +src = "." +title = "{{GROUP_NAME}} {{GROUP_TYPE}} Group" + +[output.html] +no-section-label=true +git-repository-url="https://github.com/rust-lang/{{GROUP_SLUG}}" From 953baf1f154c08adaa143d848f112168f227e424 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:16:01 -0500 Subject: [PATCH 06/11] Fix typo --- book.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book.toml b/book.toml index 81f82c7..93b82ea 100644 --- a/book.toml +++ b/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["{{GROUP_NAME}}] Members"] +authors = ["{{GROUP_NAME}} Members"] language = "en" multilingual = false src = "." From 429137db9938251a5e834fadfb8aaf01bebd58d8 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:18:12 -0500 Subject: [PATCH 07/11] Fix another typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index caa6f9e..4cede8d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Welcome to the repository for the Error Handling Project Group! We're focused on This is the repository we use to organise our work. Please refer to our [charter] for more information on our goals and current scope. - - Shepherd: + - Shepherds: - [Jane Lusby (yaahc)](https://github.com/yaahc) - [Sean Chen (seanchen1991)](https://github.com/seanchen1991) - Rust library team contact: From cb347f89375e415988aebbe6defe0d3d14ba4a5a Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:35:04 -0500 Subject: [PATCH 08/11] Flesh out 'How To Get Involved' section --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4cede8d..f0248e6 100644 --- a/README.md +++ b/README.md @@ -15,10 +15,17 @@ current scope. ## How Can I Get Involved? +Participation in this project group is open to all. You can see our work in +progress via our [open issues] on this repository and you can participate in +discussions via our [Zulip stream][chat-link]. We primarily coordinate via +our meetings, which are tracked [here][meeting-schedule]. If you're +interested in attending our meetings but can't due to a schedule conflist +please let us know on the [scheduling issue] so we can best accommodate everyone. + If you'd like to participate be sure to check out any of our [open issues] on this repository. We also participate on [Zulip][chat-link], feel free to introduce yourself over there and ask us any questions you have. [open issues]: /issues +[scheduling issue]: /issues/2 [chat-link]: https://rust-lang.zulipchat.com/#narrow/stream/257204-project-error-handling -[team-toml]: https://github.com/rust-lang/team/blob/master/teams/{{GROUP_TYPE}}-{{GROUP_SLUG}}.toml From 606f86cbb6c787b12cbde27b219df8c771cefad0 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Mon, 14 Sep 2020 16:41:32 -0500 Subject: [PATCH 09/11] Update README.md Co-authored-by: Jane Lusby --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index f0248e6..f48cf32 100644 --- a/README.md +++ b/README.md @@ -22,9 +22,6 @@ our meetings, which are tracked [here][meeting-schedule]. If you're interested in attending our meetings but can't due to a schedule conflist please let us know on the [scheduling issue] so we can best accommodate everyone. -If you'd like to participate be sure to check out any of our [open issues] on this repository. - -We also participate on [Zulip][chat-link], feel free to introduce yourself over there and ask us any questions you have. [open issues]: /issues [scheduling issue]: /issues/2 From 56c1968ee883e97ba454935647de11f6e4cea930 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 16 Sep 2020 10:13:20 -0700 Subject: [PATCH 10/11] Update CHARTER.md Co-authored-by: Ashley Mannix --- CHARTER.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHARTER.md b/CHARTER.md index 26559ef..5f99172 100644 --- a/CHARTER.md +++ b/CHARTER.md @@ -103,7 +103,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(@yaahc_), Andrew Gallant(@BurntSushi), and Sean Chen(@seanchen1991). +Jane Lusby(@yaahc), Andrew Gallant(@BurntSushi), and Sean Chen(@seanchen1991). ### Is your group long-running or temporary? @@ -119,4 +119,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 2a91c0495c3b0e59e9f2bd87ae79895a9ea16093 Mon Sep 17 00:00:00 2001 From: Sean Chen Date: Wed, 16 Sep 2020 13:26:33 -0500 Subject: [PATCH 11/11] Add KodrAus as lib team contact --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index f48cf32..3260ec5 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,8 @@ current scope. - [Jane Lusby (yaahc)](https://github.com/yaahc) - [Sean Chen (seanchen1991)](https://github.com/seanchen1991) - Rust library team contact: + - [Ashley Mannix (KodrAus)](https://github.com/KodrAus) + - Advisors: - [Andrew Gallant (BurntSushi)](https://github.com/burntsushi) [charter]: ./CHARTER.md