Repository navigation
Unstable book is a serious contribution speed bump #42454
Description
Every time I make a PR, I always get hit by the unstable book tidy check. It always takes me at least 3 roundtrips until I get it right. I hate it (the book) very much at this point.
IMO the process is unnecessarily complicated. Especially so, given that the fix usually ends up being just a link to the tracking issue – information already available to the compiler in the attribute.
I propose that the book would not require adding a link like that for every single feature and instead the pages with links to a tracking issue were generated automatically, during the generation of the book.
I do not the benefits provided by the book warrant making the contribution process so much more complicated.
Reacted by est31 and Vadim Petrochenkov
Activity
Mark-Simulacrum commentedon Jun 5, 2017
I actually think the underlying problem here is different: there is little to no point in having an unstable book if we don't utilize it to document these features. While these features are somewhat in flux due to their nature of instability, we should still document them. As such, I don't think we should auto-generate the book, though we should consider making it easier to get the initial template up for the PR author to add to as they're implementing the feature. I worry that if we auto-generate book pages then we'll end up always doing that, making the book almost useless -- something that I at least want to avoid. I've already expected to find documentation in the unstable book and been foiled more than once when trying to use an unstable feature.
cc @chriskrycho @rust-lang/docs
nagisa commentedon Jun 5, 2017
@Mark-Simulacrum does it matter that much for library features though? Library functions already get their documentation in the… documentation. There’s no benefit whatsoever in copying the library documentation into a book of some sort.
Mark-Simulacrum commentedon Jun 5, 2017
I'm not sure if we need unstable book documentation for library features, in fact I think we don't want that. I was more thinking of language features; if we currently require unstable book documentation for library features then I think we shouldn't do that (there's no point, as you've said) but should for language features. Things like catch expressions are (to my knowledge) documented effectively nowhere (except maybe in an RFC, where users don't have easy access); while I agree that the first place people land for library features is in the documentation for the standard library.
frewsxcv commentedon Jun 5, 2017
In my opinion, ideally, it'd be cool if each of the library features mentioned in the unstable book had links to all of the unstable APIs in the std docs since for one feature, there could be many unstable APIs.
est31 commentedon Jun 5, 2017
Re library features, I whole heartedly agree that their addition to the unstable should be automated during build time. See #41288
As for the lang features that only have stubs, we can simply autogenerate the stub, also at build time. Then no actual change of the unstable book is required.
steveklabnik commentedon Jun 6, 2017
Which parts do you struggle with? From my perspective, it should be "copy over an existing one and change some numbers", so knowing what the actual trouble is here should be useful.
One of the purposes of the Unstable Book is to show an overview of everything that exists and is unstable, so having something there is important, but I agree that duplicating it isn't particularly worthwhile. I mean, it'd be okay for browsing, but isn't a big deal, IMO.
Yes, this is more useful.
nagisa commentedon Jun 6, 2017
For me it usually goes like this:
est31 commentedon Jun 12, 2017
I've opened #42612 to autogenerate stubs for unstable features.