Fill in README

CHARTER.md

@@ -1,32 +1,122 @@
-# {{GROUP_NAME}} Charter
-<!--
- Provide an introduction summarising the goals and motivation behind your
- project group.
--->
+# Charter
+[charter]: #charter
 
 ## Goals
 
-<!--
- Explain what changes you'd like to see your group your group to focus on, and
- how you plan to approach these issues. Focus on explaining the highest possible
- level of your change.
--->
+### 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`.
 
-<!--
- Explain the scope of your group, what you have chosen not to include in
- your goals, and your motivations behind making them non-goals.
--->
+### 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<dyn Error...>` implement `Error`?
 
-<!--
- Mention your initial membership and who has decided take the roles of
- shepherd(s) and liason.
--->
 
-**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<dyn Error>`
+
+- 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.

README.md

@@ -1,83 +1,30 @@
-# {{GROUP_NAME}} {{GROUP_TYPE}} Group
-<!--
- This is the template for creating project groups in rust-lang. Be sure to go
- through all sections marked with `**FIX ME**`, and make sure that the text is
- correct, and feel free to replace/remove any part that's not relevant to
- your group.
+# Error Handling Project Group
 
- All of the text across all of the initial files uses the same group of
- variables to allow for easy search and replace. They are listed below.
+Welcome to the repository for the Error Handling Project Group! We're focused on defining and communicating Rust's error handling story.
 
- Example sed command: `sed -i '' 's/{{GROUP_NAME}}/Inline ASM/g' ./**/*.md`
- *Note* the `-i ''` is important as it is required on some platforms e.g. macOS
-
- * {{GROUP_NAME}} -> The display name of your group e.g. "Inline ASM".
- * {{GROUP_SLUG}} -> The url slug name of your group used for
-   `rust-lang/team` and repo name. e.g. "pg-inline-asm".
- * {{CHAT_PLATFORM}} -> The name of your chat app e.g. "Zulip".
- * {{CHAT_LINK}} -> The hyperlink to your discussions on the chat app
-   e.g. "https://rust-lang.zulipchat.com/#narrow/stream/216763-project-inline-asm".
--->
-
-<!--
- Status badge advertising the project as being actively worked on. When the
- project has finished be sure to replace the active badge with a badge
- like: https://img.shields.io/badge/status-archived-grey.svg
--->
-![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**
-
-<!--
- Provide a short introduction about your project group. Make sure to include any
- relevant links to information about your group.
--->
-
-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**
+ - Shepherds:
+    - [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
 
 ## How Can I Get Involved?
 
-**FIX ME**
-
-<!--
- List ways that people from outside your group can get involved and potentially
- become members, include what meetings your team has, and how a person could
- start participating and contributing. Make sure to mention the main platform
- your group hosts its discussions. Be sure to also include links to any
- other projects that your group maintains.
--->
-
-[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.
+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.
 
 
 [open issues]: /issues
-[chat-link]: {{CHAT_LINK}}
-[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
-```
+[scheduling issue]: /issues/2
+[chat-link]: https://rust-lang.zulipchat.com/#narrow/stream/257204-project-error-handling