Stream: project-error-handling

Topic: The Rust Error Book


view this post on Zulip must-compute (Sep 28 2020 at 22:31):

This is a general thread for items directly related to The Rust Error Book. (title pending)

view this post on Zulip must-compute (Sep 28 2020 at 22:31):

I created an mdbook repo here: https://github.com/must-compute/the-rust-error-book

view this post on Zulip must-compute (Sep 28 2020 at 22:32):

I'd like to transfer ownership to the official team account

view this post on Zulip must-compute (Sep 28 2020 at 22:32):

This repo uses the same travis config from the Rust CLI book but with slight modifications

view this post on Zulip Jane Lusby (Sep 28 2020 at 22:32):

@must-compute did you see that @Charles Ellis O'Riley Jr. is setting up the book in the project-error-handling repo?

view this post on Zulip must-compute (Sep 28 2020 at 22:32):

Oops I missed that

view this post on Zulip Jane Lusby (Sep 28 2020 at 22:32):

no worries

view this post on Zulip Charles Ellis O'Riley Jr. (Sep 28 2020 at 22:32):

Isn't tyhis the same error book I was suppose to create?

view this post on Zulip Jane Lusby (Sep 28 2020 at 22:32):

yea

view this post on Zulip Jane Lusby (Sep 28 2020 at 22:33):

no biggie

view this post on Zulip Charles Ellis O'Riley Jr. (Sep 28 2020 at 22:34):

If he has it started that's ok. I might of made the same mistake so no biggie :octopus:

view this post on Zulip must-compute (Sep 28 2020 at 22:35):

where would you like the book repo hosted @Jane Lusby (Should it be within the project group repo or as a separate repo owned by the Rust org?)

view this post on Zulip Jane Lusby (Sep 28 2020 at 22:35):

within the project group repostitory

view this post on Zulip must-compute (Sep 28 2020 at 23:30):

hmm the infra team provides guidelines for hosting:
https://forge.rust-lang.org/infra/guidelines/static-websites.html#rust-infrastructure-hosting-for-static-websites

view this post on Zulip Lokathor (Sep 28 2020 at 23:32):

Unless the error handling wg is going to have its repo live and be used forever, the error book should probably get a dedicated repo at some point.

view this post on Zulip Jane Lusby (Sep 28 2020 at 23:33):

good point

view this post on Zulip must-compute (Sep 28 2020 at 23:34):

It seems the wg-traits book followed these guidelines when setting up their book. The CLI book followed a different approach

view this post on Zulip must-compute (Sep 28 2020 at 23:35):

e.g. per these guidelines, our book URL would be rust-lang.github.io/repo-name instead of book-name.github.io
(https://rust-lang.github.io/wg-traits/ vs. https://rust-cli.github.io/book/index.html)

view this post on Zulip Jane Lusby (Sep 28 2020 at 23:46):

let's follow the guidelines

view this post on Zulip Jane Lusby (Sep 28 2020 at 23:46):

once we need to publish it permanently we can move it and give it a new home

view this post on Zulip Jane Lusby (Sep 28 2020 at 23:46):

maybe add it to the content of 'rustup doc' like the rustc dev guide

view this post on Zulip Jane Lusby (Sep 28 2020 at 23:47):

but thats way down the line I think

view this post on Zulip must-compute (Sep 28 2020 at 23:48):

So the guidelines specify things like creating a website_config.json file, but I found no occurrences of this file in any rust-lang owned repo on GH.

view this post on Zulip must-compute (Sep 29 2020 at 00:10):

I created simple a PR to initialize an mdBook folder for The Rust Error Book. The CI config and any other config files required by the infra team can be added later when needed.

view this post on Zulip DPC (Sep 29 2020 at 00:13):

the CLI book was formed in Feb 2018 iirc, the guidelines were written after that

view this post on Zulip must-compute (Sep 29 2020 at 00:13):

For reference, we can base our CI config off of the one used by wg-traits, which seems to use the steps suggested by the infra guidelines.

view this post on Zulip must-compute (Sep 29 2020 at 00:14):

@DPC ah I see now.

view this post on Zulip must-compute (Sep 29 2020 at 00:15):

makes sense, thanks for clarifying!

view this post on Zulip Jane Lusby (Sep 29 2020 at 01:52):

@must-compute turns out we had a .github workflow setup already? https://github.com/rust-lang/project-error-handling/runs/1179765271?check_suite_focus=true

view this post on Zulip Jane Lusby (Sep 29 2020 at 01:53):

your PR triggered a build failure after merge

view this post on Zulip must-compute (Sep 29 2020 at 02:07):

ah I should've checked first

view this post on Zulip must-compute (Sep 29 2020 at 02:13):

So if I understand this correctly, we can setup CI to build the book, which should resolve the workflow failure. Alternatively, we can disable the deploy-mdbook Github workflow until we set up CI to build the book. I vote for the latter option because there is no benefit in publicly deploying a book when it's far from finished.

view this post on Zulip Jane Lusby (Sep 29 2020 at 02:14):

sounds good, disable-away

view this post on Zulip must-compute (Sep 29 2020 at 02:36):

This PR should hopefully disable the deploy-mdbook workflow. I don't normally use Github workflows so I'm not 100% sure this will do the trick. The workflow never got triggered in my fork for some reason.

(I'll figure it out tomorrow)

view this post on Zulip Jane Lusby (Sep 29 2020 at 02:37):

fingers crossed

view this post on Zulip Jakub Duchniewicz (Sep 29 2020 at 07:43):

is the GH CI working?

view this post on Zulip Jakub Duchniewicz (Sep 29 2020 at 07:54):

ah I see that most other wg's base on https://github.com/rust-lang/simpleinfra/blob/master/travis-configs/static-websites.yml

view this post on Zulip Jakub Duchniewicz (Sep 29 2020 at 07:54):

we could either rewrite it to be compatible with GH pages or just stick with the old tested method

view this post on Zulip Charles Ellis O'Riley Jr. (Sep 29 2020 at 16:59):

Are the other wg’s using GH pages or the old tested methods?

view this post on Zulip Charles Ellis O'Riley Jr. (Sep 29 2020 at 17:04):

If all the different books were to be combined into one, and we elected to do it in GH pages, would it be compatible with the “old tested methods”?

view this post on Zulip Jakub Duchniewicz (Sep 29 2020 at 17:23):

I see that @must-compute did it using an already existing workflow from GH actions marketplace. Does it work? If so then the topic is probably closed :)

view this post on Zulip must-compute (Sep 29 2020 at 17:37):

@Jakub Duchniewicz the workflow was already a part of the repo before I added the book folder. The workflow is a part of the rust-lang project group template, which is what our project-error-handling repo was initially forked from.

The project group template is designed to serve the entire repo as an mdbook, but we wanted to contain the book in its own folder instead, and not to build/publish it until enough content is added (hence disabling CI and the GH workflow).

view this post on Zulip Jakub Duchniewicz (Sep 29 2020 at 17:41):

Right, I wanted to be sure it works as intended, as today I tried porting the travis code as a GH Action, but ditched it once I saw that it might be wasted effort (given we have already a working solution)

view this post on Zulip DPC (Sep 29 2020 at 18:28):

there is no plan for books to be combined iirc so don't worry about that

view this post on Zulip oliver (Oct 13 2020 at 18:21):

So I think this is a concise framework for the book attached. Early input is welcome
and I will now dive into the chapters outlined here and add subsections ahead of
the next meeting.
SUMMARY.md

view this post on Zulip Joshua Nelson (Oct 13 2020 at 18:27):

I would not call errors exceptions

view this post on Zulip Joshua Nelson (Oct 13 2020 at 18:27):

exceptions imply unwinding and Result in rust does not unwind

view this post on Zulip Joshua Nelson (Oct 13 2020 at 18:27):

maybe add a chapter on error libraries comparing what they do?

view this post on Zulip Joshua Nelson (Oct 13 2020 at 18:28):

oh that might be appendix A

view this post on Zulip oliver (Oct 13 2020 at 18:28):

Yeah that's Appendix A

view this post on Zulip Joshua Nelson (Oct 13 2020 at 18:29):

maybe call that 'comparison of error libraries', 'index of crates' made me think of the crates.io index

view this post on Zulip oliver (Oct 13 2020 at 18:30):

That should definitely be ironed out

view this post on Zulip oliver (Oct 13 2020 at 18:30):

To me Errors raise Exceptions?

view this post on Zulip oliver (Oct 13 2020 at 18:31):

I think of that Appendix as not unrelated to the index from crates.io

view this post on Zulip oliver (Oct 13 2020 at 18:34):

Updated:
SUMMARY.md

view this post on Zulip oliver (Oct 13 2020 at 18:36):

I didn't know that exceptions are exclusive to stack unwinds #til :smile:

view this post on Zulip oliver (Oct 13 2020 at 18:43):

I just thought the Error is what happens and the Exception is whatever results

view this post on Zulip oliver (Oct 13 2020 at 18:46):

So maybe call that section Objects Errors Generate?

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:13):

well, in Rust 'exception' isn't a jargon term, but in all other languages with exceptions it means unwinding

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:14):

like C++ has both error codes (left over from C) and exceptions and they're definitely different

view this post on Zulip oliver (Oct 13 2020 at 19:28):

What do you think about Objects?

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:29):

I'm not a fan of the term "object" w.r.t. Rust code. That said, people know what you mean.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:29):

IMO "object" == instance of "class", but Rust has no classes.

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:30):

Trait Object is okay imo

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:30):

not sure if thats what is being talked about rn tho

view this post on Zulip oliver (Oct 13 2020 at 19:31):

There is a chapter I proposed called Kinds of Exceptions that might be changed
to Objects Errors Generate

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:31):

My go-to replacement for "object" (not trait object) is "value"

view this post on Zulip oliver (Oct 13 2020 at 19:31):

Values is vague to me

view this post on Zulip oliver (Oct 13 2020 at 19:32):

But we are looking for precision not impression

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:32):

https://doc.rust-lang.org/stable/reference/expressions.html?highlight=value#place-expressions-and-value-expressions

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:32):

i think value is the technical term used in rust documentation

view this post on Zulip oliver (Oct 13 2020 at 19:32):

I think I mean Trait Objects

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:32):

for instances of types

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:33):

A value expression is an expression that represents an actual value.

view this post on Zulip oliver (Oct 13 2020 at 19:33):

So a value is a value?

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:34):

yes, but I'm not following your point.

view this post on Zulip oliver (Oct 13 2020 at 19:34):

Precision

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:35):

Jake Goulding said:

IMO "object" == instance of "class", but Rust has no classes.

well technically object just means 'region of memory' in C (I think, been a while since I read the standard)

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:35):

but I agree that's not how most people will interpret it

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:35):

struct Error; is not a trait object, FWIW.

view this post on Zulip oliver (Oct 13 2020 at 19:36):

But struct Error is an Object?

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:36):

@Joshua Nelson "IMO" ≠ "technically"

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:36):

oliver said:

But struct Error is an Object?

no, it's a type

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:36):

or if you have a concrete let err: Error it's a value

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:36):

@oliver you've back-tick-quoted "Object", but there's no code called Object.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:37):

For the discussion, I should not have used a zero-member type.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:37):

struct Error(i32) is a type. Error(1) is a value.

view this post on Zulip oliver (Oct 13 2020 at 19:37):

A trait object is a struct of unspecified layout, no?

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:37):

no

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:37):

Box<dyn Error> is a trait object type.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:38):

Box::new("hi") as Box<dyn Error> is a trait object value.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:38):

(untested code, for demo purposes only)

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:39):

It is fairly rare for me to use trait object types/values as my error types / values.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:40):

So, depending on what exactly you are writing about, trait objects may be over-constraining the design space.

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:40):

heh, i think you'd need an into but yea

view this post on Zulip oliver (Oct 13 2020 at 19:40):

Well I was trying to express that we would cover the underlying structures
involved

view this post on Zulip oliver (Oct 13 2020 at 19:41):

I imagined that the second chapter would be more about the abstractions

view this post on Zulip oliver (Oct 13 2020 at 19:44):

So it looks like underneath all Errors generally speaking we talk about values?

view this post on Zulip Joshua Nelson (Oct 13 2020 at 19:45):

yes, in general

view this post on Zulip oliver (Oct 13 2020 at 19:45):

Interesting :thinking:

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:45):

looking at the summary rn btw

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:45):

What does "Designing Error Handlers" mean?

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:46):

I don't know exactly what you mean by "underneath all Errors" :-)

view this post on Zulip oliver (Oct 13 2020 at 19:46):

Abstractions

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:46):

Also at a minimum I think we should aim to add a section on error reporting as well as one for error handling and FFI

view this post on Zulip oliver (Oct 13 2020 at 19:47):

Jake Goulding said:

I don't know exactly what you mean by "underneath all Errors" :-)

Well like the technical etymology of an Error in Rust

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:48):

And I'd like us to break down the aspects of error handling the same way I did in my talk, namely "defining, propagating, reacting, discarding, and reporting"

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:48):

hmm, that edit made it worse for me :-)

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:48):

hmm?

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:48):

you wanted handling over propagating?

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:49):

I feel like handling the superset that encompasses those 5 sub categories

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:49):

Neither "handling" nor "propagating" reflect "make a new error" to me.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:49):

What I call "leaf errors".

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:49):

Perhaps "generating"

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:49):

i think that falls under defining personally

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:49):

i guess there could also be constructing

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:49):

IMO "defining" == type level.

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:50):

which would be the value side where defining is the type side

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:50):

sure

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:50):

I can dig that

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:50):

constructing would make sense too

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:50):

okay so six categories

view this post on Zulip Charles Ellis O'Riley Jr. (Oct 13 2020 at 19:50):

I think writing on the best way to handle errors, in user friendly terminology, would lower the barrier to entry in learning Rust

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:51):

in user friendly terminology

A perpetual dilemma is do you use "friendly" terminology or the currently accepted one?

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:51):

e.g. Rust's "lifetimes" are not friendly (that's a different, off-topic discussion), but there's not much hope to change that now.

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:52):

That also presupposes that there's a best way.

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:52):

I favor using consistent terminology but if we can highlight terminology that is specifically user unfriendly I think we could try to change that terminology across the rust project

view this post on Zulip Jake Goulding (Oct 13 2020 at 19:53):

consistent is a great start. A glossary with expanded definitions is also useful. And introducing the terms throughly when first used, of course.

view this post on Zulip Jane Lusby (Oct 13 2020 at 19:56):

agreed, theres already a bit of this in the Charter, so we should definitely make sure to copy over any information there that is relevant to the book

view this post on Zulip oliver (Oct 13 2020 at 19:58):

Here's the latest: https://cryptpad.fr/code/#/2/code/edit/1FhyaBOOANgdSTKA8xbYIt8t/

view this post on Zulip oliver (Oct 13 2020 at 20:00):

I would start on subsections once the chapter outline is finished

view this post on Zulip Jane Lusby (Oct 13 2020 at 20:14):

My feeling is that the first two sections in the summary will have a lot of overlap with the later ones, and that we should lead with fundamentals

view this post on Zulip Jane Lusby (Oct 13 2020 at 20:15):

like, values errors return seems like a subsection of "constructing"

view this post on Zulip Jane Lusby (Oct 13 2020 at 20:15):

not something that we should lead with

view this post on Zulip Jane Lusby (Oct 13 2020 at 20:15):

examples are good though

view this post on Zulip Jane Lusby (Oct 13 2020 at 20:15):

I wouldn't mind starting with examples and then starting to explain them

view this post on Zulip oliver (Oct 13 2020 at 20:22):

Right, now it goes from a technical overview of how Error values exist, to an
intro example then a section on the philosophy of what error handling means in
Rust from there the following sections are more concrete

view this post on Zulip oliver (Oct 13 2020 at 20:23):

Fundamentals -> Parts of Error Handling -> Patterns -> FFI -> Glossary ->
Appendix

view this post on Zulip Jane Lusby (Oct 13 2020 at 21:03):

sounds good

view this post on Zulip Nelson J Morais (Oct 14 2020 at 10:13):

why not use the rust terminology but add a parenthesis with a more "wider and friendlier (read less technical) description when applicable?

view this post on Zulip oliver (Oct 14 2020 at 13:23):

It's generally not ideal to have multiple competing terms for the same concept

view this post on Zulip oliver (Oct 14 2020 at 13:29):

Leads to confusion and moral panic and inflates word counts

view this post on Zulip DPC (Oct 14 2020 at 14:05):

what we do with another book is make small prs and use placeholders for the rest, so people can read the book after prs get merged even though the entire book is incomplete

view this post on Zulip oliver (Oct 14 2020 at 18:08):

That works or using (sic) also helps flag odd terms

view this post on Zulip Jake Goulding (Oct 14 2020 at 18:10):

I'm not an English major, but AIUI sic is to be used when something is wrong but you are including it verbatim.

view this post on Zulip Jake Goulding (Oct 14 2020 at 18:10):

"Their name was Richhard [sic]"

view this post on Zulip oliver (Oct 14 2020 at 18:10):

Colloquially it can be used where something else is intended

view this post on Zulip Jake Goulding (Oct 14 2020 at 18:11):

Ah sorry, thought the goal was precision over colloquialism.

view this post on Zulip Jake Goulding (Oct 14 2020 at 18:11):

Both are valuable.

view this post on Zulip oliver (Oct 14 2020 at 18:13):

Like in a draft when you need to flag something as imprecise, otherwise it's
like you say and should be reserved for something known to be incorrect for a
reason, (sic) just happens to be both keyword searchable and had some general context

view this post on Zulip Jake Goulding (Oct 14 2020 at 18:14):

ah, usage in a draft is also not what I was thinking of. I do the same in my code (a lot of variables like zxc or qqq to be easily renamed later)

view this post on Zulip oliver (Oct 14 2020 at 18:15):

To each their own :star:

view this post on Zulip oliver (Oct 14 2020 at 18:16):

I guess with (sic) I always think I could publish this as is and apologize
about it after :joy:

view this post on Zulip oliver (Oct 14 2020 at 18:23):

(se) would probably work just as well and less a char but maybe isn't widely recognized
as denoting an intentional error or inaccuracy

view this post on Zulip oliver (Oct 14 2020 at 18:27):

and se's like 'se what?' and sic's like 'oh sic'

view this post on Zulip DPC (Oct 14 2020 at 19:53):

sic is mostly used to quote someone else "by word"

view this post on Zulip oliver (Oct 14 2020 at 21:10):

"It also applies to any surprising assertion, faulty reasoning, or other
matter that might be likely interpreted as an error of transcription. "
-Wikipedia Contributors

view this post on Zulip oliver (Oct 14 2020 at 21:10):

To each their own :star:

view this post on Zulip oliver (Oct 14 2020 at 21:16):

I guess one of the more interesting things about languages is they evolve


Last updated: Jan 29 2022 at 10:01 UTC