o/ @Yoshua Wuyts
one thing that would be tremendously helpful that I haven't had the time to investigate is a way to set up the book so that we can actually reference sections of code from the docs that is actually getting run and tested in CI, to ensure that we can make changes and edit with confidence that the code still compiles
I know there are a variety of solutions to this in the wild, but I'm not familiar with that space
@Taylor Cramer is it an mdbook?
If so, it's pretty easy
@nikomatsakis currently it's just a set of markdown files, or it was when I last touched it
but that sounds like a great change to make ;)
Ohey, I didn't get a notifcation for this. Thanks for making this channel @Taylor Cramer!
I guess I was wondering about two things:
1. how do we present the book to the public?
2. how do we schedule & contribute content so by mid-August we have a solid reference the rust community can use?
Regarding presentation -- currently the book is under rust-lang/async-book. Similar to rust-lang/book, but different from rust-wasm/book and rust-cli/book.
There's also a wider conversation happening on whether the domain books should be bundled with
rustup doc, and/or how to present them online -- currently the entrypoint for most people would be https://www.rust-lang.org/learn
I was thinking that perhaps a good way to get people to contribute / manage the async-book would be if it could live as part of
rustasync/book, as a counterpart to
rust-cli/book (which might get renamed to
rustcli/book at some point too).
Which ties into question 2: How do we plan the content for async-book?
I feel the current outline is really good! Folks in the async eco wg have expressed interest in contributing; I was thinking if perhaps we could make this a regular part of the meetings so we can make steady progress on it, week over week.
I think with the current outline we could hit that goal quite easily ^^.
Anyway, I feel like I've typed a lot this morning, haha. That's all I had! -- keen to hear thoughts!
ping @Taylor Cramer I'd love to get your thoughts on ^
1) not sure what presentation you had in mind, but I think nmatsakis's suggestion to make it an mdbook was a good one, get a copy hosted, link it from the futures-rs docs as well as potentially the main rust site
2) having a regular checking and creating tracking issues are probably good first steps. does meeting 30 minutes before the main async foundations wg meeting work for you?
WRT planning content: yeah, I think the current table-of-contents reflects my own opinion, and if folks have other sections they feel like contributing I think the right step would be to open issues and we could triage them in our weekly meeting
@Yoshua Wuyts does that roughly match your expectations?
@Taylor Cramer it does!
meeting 30 mins before sounds good! -- is there a way we could put that on the calendar?
my only comment on the outline is that I think it might make sense to do a bit more "high-level" material before diving into the futures trait details
Cool! I'll start making and assigning some issues today, and we can start divvying up work. Yeah, although the compiler team calendar is kind of a funny bbit
@nikomatsakis there's some of that in the introduction and the initial async/await example, but those could be expanded. Is there some specific content you were hoping to cover in that?
I can give you perms to edit compiler/lang team calendars
I'll let async eco WG memebers know about this too; there has been interest in contributing for a while
@nikomatsakis that would be great!
I think it may be more a matter of rearranging the table of contents
@Yoshua Wuyts awesome! glad to hear it
@nikomatsakis makes sense
i.e., the async-await primer section is close to what I was thinking, but I might pull it out to a more prominent chapter
I kind of glazed over it at first, just looking at the "major headings"
I'd probably incorporate the runtime crate so that you can have an
async fn main and walk through some kind of thing like the guessing game
which is quite trivial but also complex enough to be interesting
I guess that is roughly what is happening in Applied: HTTP Server
so maybe it's mostly a matter of calling attention to what's there -- I was thinking a heading like
"Writing code with async-await"
which sounds a bit less "beginner and boring" than "Getting started" :)
but i'm not sure, maybe I'm just wrong
@nikomatsakis yeah, although there's a dedicated async/await! chapter later on that goes into more details
yeah, I guess i'm debating how much depth to go into before tackling the futures trait
My opinion has always been "not that much", as it's really helpful to understand in order to use async/await correctly. It's a very leaky abstraction.
(and FWIW the coworkers i've had who learned async/await without learning the Future trait first have reported that they had some confusions as a result)
Put it on the eco WG agenda!
I'd definitely be curious to hear more details
(I've got to run again; talk to y'all offline / next week!)
It seems likely that we have to teach some parts of the model but I feel like you should not have to learn about (e.g.)
Pin in order to get productive work done
@nikomatsakiswhen you get a chance, can you either add an event for async-book-meeting or give me permissions to edit the calendar?
@Taylor Cramer done -- you should be able to edit calendar
@nikomatsakis great, added a book meeting event
where is the calendar?
update on book things:
I've gotten link checker running on the book and am working to pull out the example code into separate projects in an examples/ workspace inside the async book repo, update those to the current library/syntax, and get tests running in CI. Once that's done, it should be easier to start accepting PRs for new content.
If anyone wants to start working on content, feel free to take a look at the table of contents: https://github.com/rust-lang/async-book/blob/master/src/SUMMARY.md, and open an issue mentioning that you plan to get started
there's a lot there left
TODO, and I'll aim to have a PR up today with the examples and everything factored out so we can get started
@Taylor Cramer (queston -- did you mean to start a "meeting topic"?)
(or shall I?)
@nikomatsakis I did not, since currently "async book" was its own topic and I was hoping to notify the people already in this topic
but perhaps "async book" should be made into its own stream
so that we can have subtopics within it
I can create a #wg-async-foundations/book if you like
that would be great!