Skip to content
This repository has been archived by the owner on Sep 12, 2024. It is now read-only.

Commit

Permalink
Merge pull request #1 from seanchen1991/master
Browse files Browse the repository at this point in the history 
Fill in README
  • Loading branch information
@seanchen1991
seanchen1991 authored Sep 16, 2020
2 parents 621de18 + 2a91c04 commit 1c74367
Show file tree
Hide file tree
Showing 2 changed files with 132 additions and 95 deletions.
136 changes: 113 additions & 23 deletions CHARTER.md
View file
Original file line number Diff line number Diff line change
@@ -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.
91 changes: 19 additions & 72 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 1c74367

Please sign in to comment.