Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Unstable Book Updates needed #57224

Closed
ZerothLaw opened this issue Dec 30, 2018 · 7 comments
Closed

Unstable Book Updates needed #57224

ZerothLaw opened this issue Dec 30, 2018 · 7 comments
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools A-stability Area: `#[stable]`, `#[unstable]` etc. C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC T-lang Relevant to the language team, which will review and decide on the PR/issue.

Comments

@ZerothLaw
Copy link

Mostly listing parts of the book that need work, need tracking updates, etc.

  • abi_x86_interrupt - Unlikely to ever be stabilized, could probably move the documentation from the tracking issue to the book
  • allow_fail - link doesn't go to a tracking issue but the initial PR that added the feature
  • bind_by_move_pattern_guards - obsoleted by NLL work, will probably be closed soon
  • cfg _target_thread_local - links to the same tracking issue as thread_local does, which is confusing.
  • cfg_target_vendor - been unstable for nearly four years now, no listed reason in the tracking issue for why it is still unstable
  • crate_visibility_modifier - links to a now-closed tracking issue
  • custom_derive - links to a now-closed tracking issue
  • doc_alias - could be stabilized?
  • exhaustive_integer_patterns - has been stabilized
  • existential_type - mismatch between name of feature, and the name of the tracking issue. Perhaps incorrect tracking issue?

Taking a break, will add more later.

@Centril Centril added A-stability Area: `#[stable]`, `#[unstable]` etc. A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC labels Dec 31, 2018
@Centril
Copy link
Contributor

Centril commented Dec 31, 2018

@Centril Centril added the T-lang Relevant to the language team, which will review and decide on the PR/issue. label Dec 31, 2018
@mark-i-m
Copy link
Member

mark-i-m commented Jan 2, 2019

I think we need to rethink the unstable book altogether. Every time I have gone to it, it has been... unhelpful. Usually, I just end up reading the tracking issue anyway. Perhaps what we want instead is an automatically generated index of features... something like a table a like this:

feature tracking issue status
asm #29722 implemented, but buggy

Though maybe the status is better left to the tracking issue unless we can find a way to update it automatically...

@ZerothLaw
Copy link
Author

Yeah, that seems to be the issue in the ones I looked at. If we think of it as source code, the Unstable book depends on those tracking issues. But because there's no checking of the tracking issues, the source code becomes outdated and defective.

@steveklabnik
Copy link
Member

steveklabnik commented Jan 10, 2019

@mark-i-m i have also felt like the unstable book is not meeting its goals. I would be open to the idea of a single page, with the feature names and tracking issues.

Furthermore, the unstable book was made a book with the idea that it could be where documentation lands before the feature does, but given the new changes to the rfc process that @nikomatsakis and others have been talking about, if those changes go through, there will be a new place for them to live, de-ephasizing the "book" nature of the unstable book all together.

@mark-i-m
Copy link
Member

I’m curious if you think that should be done as part of broader RFC reform or as its own measure?

@mark-i-m
Copy link
Member

Specifically, I think that any successful process reforms will need to include heavy automation to scale well.

@Mark-Simulacrum
Copy link
Member

Closing this issue after brief discussion in lang backlog bonanza. It doesn't seem like this is driving any real improvement here. Today the unstable book appears auto-generated, at least for lang features, which likely means we have at least a page for each item.

If we want to drive more meaningful content, I think we likely need either automation or better process around updating these pages -- we're generally not great about documentation updates, particularly for unstable features, but it seems like that's something we're slowly trying to do better on (e.g., see lang initiative work). Connecting language unstable features to their initiatives seems like an OK thing to do.

I think the primary value in pulling this info out of tracking issues is likely better searchability, as well as encouraging more documentation-y vs. comment-y writing. That does seem valuable to me.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools A-stability Area: `#[stable]`, `#[unstable]` etc. C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC T-lang Relevant to the language team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

5 participants