Add context to dated information (#1013)

* Fixes #924 Add context to dated information

* Fixes #924 Addressed comments and some uses of 'currently'

* Update src/contributing.md

Co-authored-by: Joshua Nelson <[email protected]>

* Update src/salsa.md

Co-authored-by: Joshua Nelson <[email protected]>

* Fixes #924 Addressed comments

* Fixes #924 Fixed line lengths.

Co-authored-by: Joshua Nelson <[email protected]>

Author: igaray

src/SUMMARY.md

@@ -107,7 +107,6 @@
         - [Lowering to logic](./traits/lowering-to-logic.md)
         - [Goals and clauses](./traits/goals-and-clauses.md)
         - [Canonical queries](./traits/canonical-queries.md)
-        - [Lowering module in rustc](./traits/lowering-module.md)
 - [Type checking](./type-checking.md)
     - [Method Lookup](./method-lookup.md)
     - [Variance](./variance.md)

src/about-this-guide.md

@@ -30,10 +30,27 @@ There are six parts to this guide:
 [p5]: ./part-5-intro.md
 [app]: ./appendix/background.md
 
-The Guide itself is of course open-source as well, and the sources can
-be found at the [GitHub repository]. If you find any mistakes in the
-guide, please file an issue about it, or even better, open a PR
-with a correction!
+### Constant change
+
+Keep in mind that `rustc` is a real production-quality product, being worked upon continuously by a
+sizeable set of contributors.
+As such, it has its fair share of codebase churn and technical debt.
+In addition, many of the ideas discussed throughout this guide are idealized designs that are not
+fully realized yet.
+All this makes keeping this guide completely up to date on everything very hard!
+
+The Guide itself is of course open-source as well, and the sources can be found at the
+[GitHub repository].
+If you find any mistakes in the guide, please file an issue about it, or even better, open a PR with
+a correction!
+
+If you do contribute to the guide, please see the corresponding
+[subsection on writing documentation in this guide].
+
+[subsection on writing documentation in this guide]: contributing.md#contributing-to-rustc-dev-guide.
+
+> “‘All conditioned things are impermanent’ — when one sees this with wisdom, one turns away from
+> suffering.” _The Dhammapada, verse 277_
 
 ## Other places to find information
 

src/backend/backend-agnostic.md

@@ -1,8 +1,7 @@
 # Backend Agnostic Codegen
 
-In the future, it would be nice to allow other codegen backends (e.g.
-[Cranelift]). To this end, `rustc_codegen_ssa` provides an
-abstract interface for all backends to implement.
+As of January 2021, `rustc_codegen_ssa` provides an abstract interface for all backends to
+implement, to allow other codegen backends (e.g. [Cranelift]).
 
 [Cranelift]: https://github.com/bytecodealliance/wasmtime/tree/HEAD/cranelift
 

src/borrow_check/region_inference/member_constraints.md

@@ -92,8 +92,9 @@ member constraints come in.
 ## Choices are always lifetime parameters
 
 At present, the "choice" regions from a member constraint are always
-lifetime parameters from the current function. This falls out from the
-placement of impl Trait, though in the future it may not be the case.
+lifetime parameters from the current function. As of January 2021,
+this falls out from the placement of impl Trait, though in the future
+it may not be the case.
 We take some advantage of this fact, as it simplifies the current
 code. In particular, we don't have to consider a case like `'0 member
 of ['1, 'static]`, in which the value of both `'0` and `'1` are being

src/contributing.md

@@ -401,11 +401,28 @@ You can also use `rustdoc` directly to check small fixes. For example,
 `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.
 The CSS might be messed up, but you can verify that the HTML is right.
 
-Additionally, contributions to the [rustc-dev-guide][rdg] are always welcome.
-Contributions can be made directly at [the rust-lang/rustc-dev-guide
-repo][rdgrepo]. The issue tracker in that repo is also a great way to find
-things that need doing. There are issues for beginners and advanced compiler
-devs alike!
+### Contributing to rustc-dev-guide
+
+Contributions to the [rustc-dev-guide][rdg] are always welcome, and can be made directly at
+[the rust-lang/rustc-dev-guide repo][rdgrepo].
+The issue tracker in that repo is also a great way to find things that need doing.
+There are issues for beginners and advanced compiler devs alike!
+
+Just a few things to keep in mind:
+
+- Please limit line length to 100 characters. This is enforced by CI, and you can run the checks
+  locally with `ci/check_line_lengths.sh`.
+- When contributing text to the guide, please contextualize the information with some time period
+  and/or a reason so that the reader knows how much to trust or mistrust the information.
+  Aim to provide a reasonable amount of context, possibly including but not limited to:
+  - A reason for why the data may be out of date other than "change", as change is a constant across
+    the project.
+  - A date the comment was added, e.g. instead of writing _"Currently, ..."_ consider writing
+    _"As of January 2021, ..."_.
+    Try to format the date as `<MONTH> <YEAR>` to ease search.
+  - A link to a relevant WG, tracking issue, `rustc` rustdoc page, or similar, that may provide
+    further explanation for the change process or a way to verify that the information is not
+    outdated.
 
 [rdg]: https://rustc-dev-guide.rust-lang.org/
 [rdgrepo]: https://github.com/rust-lang/rustc-dev-guide

src/debugging-support-in-rustc.md

@@ -93,8 +93,6 @@ document so there is no duplication etc.?
 
 ### LLDB
 
-We have our own fork of LLDB - [https://github.com/rust-lang/lldb]
-
 Fork of LLVM project - [https://github.com/rust-lang/llvm-project]
 
 LLDB currently only works on macOS because of a dependency issue. This issue was easier to

src/diagnostics.md

@@ -594,7 +594,7 @@ declare_lint! {
 
 If you need a combination of options that's not supported by the
 `declare_lint!` macro, you can always define your own static with a type of
-`&Lint` but this is currently linted against in the compiler tree.
+`&Lint` but this is (as of January 2021) linted against in the compiler tree.
 
 <a id="future-incompatible"></a>
 ####  Guidelines for creating a future incompatibility lint

src/diagnostics/lintstore.md

@@ -15,9 +15,11 @@ Unfortunately, a lot of the documentation we have refers to both of these as jus
 
 First, we have the lint declarations themselves: this is where the name and default lint level and
 other metadata come from. These are normally defined by way of the [`declare_lint!`] macro, which
-boils down to a static with type `&rustc_session::lint::Lint`. We lint against direct declarations
-without the use of the macro today (though this may change in the future, as the macro is somewhat
-unwieldy to add new fields to, like all macros by example).
+boils down to a static with type `&rustc_session::lint::Lint`.
+
+As of January 2021, we lint against direct declarations without the use of the macro today
+(although this may change in the future, as the macro is somewhat unwieldy to add new fields to,
+like all macros by example).
 
 Lint declarations don't carry any "state" - they are merely global identifers and descriptions of
 lints. We assert at runtime that they are not registered twice (by lint name).

src/git.md

@@ -145,8 +145,10 @@ no changes added to commit (use "git add" and/or "git commit -a")
 These changes are not changes to files: they are changes to submodules
 (more on this [later](#git-submodules)). To get rid of those, run `git submodule update` (or run any
 `x.py` command, which will automatically update the submodules).
-Note that there is currently a bug if you use worktrees, submodules, and x.py in a commit hook.
+Note that there is (as of January 2021) a bug if you use worktrees, submodules, and x.py in a commit
+hook.
 If you run into an error like:
+
 ```
 error: failed to read `/home/joshua/rustc-worktree/src/tools/miri/cargo-miri/Cargo.toml`
 
@@ -202,7 +204,7 @@ rebase. The section between `<<<<<<< HEAD` and `=======` has the code from
 master, while the other side has your version of the code. You'll need to
 decide how to deal with the conflict. You may want to keep your changes,
 keep the changes on master, or combine the two.
- 
+
 Generally, resolving the conflict consists of two steps: First, fix the
 particular conflict. Edit the file to make the changes you want and remove the
 `<<<<<<<`, `=======` and `>>>>>>>` lines in the process. Second, check the
@@ -311,7 +313,7 @@ This is because, like any dependency, we want to be able to control which versio
 Submodules allow us to do just that: every submodule is "pinned" to a certain
 commit, which doesn't change unless modified manually. If you use `git checkout <commit>`
 in the `miri` directory and go back to the `rust` directory, you can stage this
-change like any 
+change like any
 This is usually done by
 the maintainers of the project, and looks like [this][miri-update].
 

src/llvm-coverage-instrumentation.md

@@ -219,7 +219,7 @@ properly-configured variables in LLVM IR, according to very specific
 details of the [_LLVM Coverage Mapping Format_][coverage-mapping-format]
 (Version 4).[^llvm-and-covmap-versions]
 
-[^llvm-and-covmap-versions]: The Rust compiler currently supports
+[^llvm-and-covmap-versions]: The Rust compiler (as of January 2021) supports
 _LLVM Coverage Mapping Format_ Version 4 (the most up-to-date version
 of the format, at the time of this writing) for improved compatibility
 with other LLVM-based compilers (like _Clang_), and to take advantage