Tracking Issue: Error Handling Book

[yaahc]

This is the tracking issue for progress writing an Error Handling Book documenting the error handling project group's work to produce a markdown book comprehensively documenting error handling in Rust.

Related Documents

• Summary document and notes from previous meetings
• Prior Art: https://github.com/rust-lang/project-error-handling/issues/24

Todo

• [ ] @yaahc: Summarize existing notes from previous meetings and move notes document to the lib's team HackMD
• [ ] @nagashi: Create a diagram showing how the various pieces of error handling relate to each other
• [ ] @seanchen1991: Write an updated minigrep example using 3rd party libraries for a full and idiomatic implementation of error handling
• [ ] Write the rest of the owl Book

Completed

• [x] Summarize the conclusions of this zulip thread in a comment in this tracking issue

[yaahc]

In https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/3rd.20party.20libraries.20in.20official.20books.2Fdocumentation we discussed whether it would be appropriate to include 3rd party error handling libraries in the Error Handling Book, and the trade offs of doing so vs not. The general sentiment seemed to be that the advantages of giving users concrete examples that they can then apply to their own code outweigh the costs of potentially favoring particular 3rd party libraries or mentioning libraries that aren't maintained by the project in official project documentation. We also felt that it would be best to choose a transparent and objective method for deciding on which crates to use in our examples, so that it's clear when its appropriate to add a new library to the book or swap out an old one.

Based on this discussion we've come up with the following plan:

• [ ] Create a new set of categories on crates.io related to error handling
• [ ] Release an blog post announcing our intention to write a book about error handling
• [ ] Describe the issue with third party libraries, and our assessment of the best approach
• [ ] Describe how we're going to pick which libraries are going to go into the book
• [ ] Encourage authors of error handling crates to update their libraries to use the new tags (might be worth helping out with this effort proactively)
• [ ] Make it clear that this is all our current plan, and that we're interested in feedback and open to changing our plan

Then once this is all done we start writing the book ^_^. In the book we will need to emphasize that the crates mentioned are 3rd party crates and not controlled by the libs team or rust project.

[nagashi]

Jane,

Will this also be a part of the diagram?

On Fri, Apr 16, 2021 at 17:47 Jane Lusby @.***> wrote:

In https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/topic/3rd.20party.20libraries.20in.20official.20books.2Fdocumentation we discussed whether it would be appropriate to include 3rd party error handling libraries in the Error Handling Book, and the trade offs of doing so vs not. The general sentiment seemed to be that the advantages of giving users concrete examples that they can then apply to their own code outweigh the costs of potentially favoring particular 3rd party libraries or mentioning libraries that aren't maintained by the project in official project documentation. We also felt that it would be best to choose a transparent and objective method for deciding on which crates to use in our examples, so that it's clear when its appropriate to add a new library to the book or swap out an old one.

Based on this discussion we've come up with the following plan:

• Create a new set of categories on crates.io related to error handling
• Release an blog post announcing our intention to write a book about error handling
• Describe the issue with third party libraries, and our assessment of the best approach
• Describe how we're going to pick which libraries are going to go into the book
• Encourage authors of error handling crates to update their libraries to use the new tags (might be worth helping out with this effort proactively)
• Make it clear that this is all our current plan, and that we're interested in feedback and open to changing our plan

In the book we will need to emphasize that the crates mentioned are 3rd party crates and not controlled by the libs team or rust project.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/rust-lang/project-error-handling/issues/38#issuecomment-821673122, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAOCIZ7BKQSUG3ON7S4IGITTJC467ANCNFSM43CKWN6A .

-- CEO’Riley

[yaahc]

None of the specific libraries will be in the diagram, but we might want to include the crates.io categories.