Skip to content

Add context to "may be out of date" sections #924

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

Closed
workingjubilee opened this issue Oct 19, 2020 · 2 comments
Closed

Add context to "may be out of date" sections #924

workingjubilee opened this issue Oct 19, 2020 · 2 comments
Assignees

Comments

@workingjubilee
Copy link
Member

workingjubilee commented Oct 19, 2020

Many places in the guide mention "this section may be out of date", such as in the parser. This is unfortunately quite ambiguous because the writer usually has not contextualized it with a "when" or "why", and so the reader does not know how much to trust or mistrust the information. Such comments should be marked with enough data to provide a reasonable amount of context, possibly including but not limited to

  1. a reason for why the data may be out of date other than "change"... change is a constant across the project
  2. a time the comment was added (visible in git blame but not on the website)
  3. a link to a relevant WG, tracking issue, or similar, that may provide further explanation for the change process
@workingjubilee
Copy link
Member Author

It's probably worth lifting this caveat from the "high-level overview of the compiler" into "About this guide": https://rustc-dev-guide.rust-lang.org/overview.html#constant-change

That way we clearly assert the base case of change initially.
Places we can update that assert the contents are possibly dated or that themselves might need an update due to time passing:

This is a good example to reference: Specialization - Additional Resources. Something might have been dated, and is out of the guide's bounds, so it is unlikely to update, but it is given a time it dates to in the guide, so the reader can choose whether or not to click at all.

@igaray
Copy link
Member

igaray commented Dec 27, 2020

@rustbot claim

igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 9, 2021
igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 9, 2021
igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 9, 2021
igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 10, 2021
igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 10, 2021
igaray added a commit to igaray/rustc-dev-guide that referenced this issue Jan 10, 2021
@igaray igaray closed this as completed in 0a5bb7f Jan 10, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants