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 <joshua@yottadb.com>

* Update src/salsa.md

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

* Fixes #924 Addressed comments

* Fixes #924 Fixed line lengths.

Co-authored-by: Joshua Nelson <joshua@yottadb.com>

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

src/miri.md

@@ -191,7 +191,7 @@ concrete integer.
 
 However, a variable of pointer or reference *type*, such as `*const T` or `&T`,
 does not have to have a pointer *value*: it could be obtaining by casting or
-transmuting an integer to a pointer (currently that is hard to do in const eval,
+transmuting an integer to a pointer (as of January 2021 that is hard to do in const eval,
 but eventually `transmute` will be stable as a `const fn`).  And similarly, when
 casting or transmuting a reference to some actual allocation to an integer, we
 end up with a pointer *value* (`Scalar::Ptr`) at integer *type* (`usize`).  This

src/opaque-types-type-alias-impl-trait.md

@@ -14,7 +14,7 @@ This declares an opaque type named `Foo`, of which the only information is that
 it implements `Bar`. Therefore, any of `Bar`'s interface can be used on a `Foo`,
 but nothing else (regardless of whether it implements any other traits).
 
-Since there needs to be a concrete background type, you can currently
+Since there needs to be a concrete background type, you can (as of January 2021)
 express that type by using the opaque type in a "defining use site".
 
 ```rust,ignore

src/overview.md

@@ -15,7 +15,6 @@ So first, let's look at what the compiler does to your code. For now, we will
 avoid mentioning how the compiler implements these steps except as needed;
 we'll talk about that later.
 
-
 - The compile process begins when a user writes a Rust source program in text
   and invokes the `rustc` compiler on it. The work that the compiler needs to
   perform is defined by command-line options. For example, it is possible to
@@ -159,17 +158,6 @@ satisfy/optimize for. For example,
 So, as you read through the rest of the guide, keep these things in mind. They
 will often inform decisions that we make.
 
-### Constant change
-
-Keep in mind that `rustc` is a real production-quality product.
-As such, it has its fair share of codebase churn and technical debt. A lot of
-the designs discussed throughout this guide are idealized designs that are not
-fully realized yet. And things keep changing so that it is hard to keep this
-guide completely up to date on everything!
-
-The compiler definitely has rough edges, but because of its design it is able
-to keep up with the requirements above.
-
 ### Intermediate representations
 
 As with most compilers, `rustc` uses some intermediate representations (IRs) to

src/parallel-rustc.md

@@ -1,9 +1,10 @@
 # Parallel Compilation
 
 Most of the compiler is not parallel. This represents an opportunity for
-improving compiler performance. Much effort has been put into parallelizing
-`rustc`, but it is still pretty early days for this work. There is a lot of
-design and correctness work that needs to be done.
+improving compiler performance.
+
+As of January 2021, work on explicitly parallelizing the compiler has stalled.
+There is a lot of design and correctness work that needs to be done.
 
 One can try out the current parallel compiler work by enabling it in the
 `config.toml`.

src/profiling.md

@@ -90,5 +90,5 @@ The llvm-lines output is affected by several options.
 
 MIR optimizations have little impact. Compared to the default `RUSTFLAGS="-Z mir-opt-level=1"`,
 level 0 adds 0.3GB and level 2 removes 0.2GB.
-Inlining currently only happens in LLVM, but this might change in the future.
+As of January 2021, inlining currently only happens in LLVM but this might change in the future.
 

src/queries/incremental-compilation-in-detail.md

@@ -207,7 +207,7 @@ This comes with a whole new set of implementation challenges:
   Fixed-sized, plain-old-data is preferred to complex things that need to run
   through an expensive (de-)serialization step.
 
-The following sections describe how the compiler currently solves these issues.
+The following sections describe how the compiler solves these issues.
 
 ### A Question Of Stability: Bridging The Gap Between Compilation Sessions
 

src/queries/profiling.md

@@ -2,7 +2,7 @@
 In an effort to support _incremental compilation_, the latest design of the Rust
 compiler consists of a _query-based_ model.
 
-The details of this model are (currently) outside the scope of this document,
+The details of this model are outside the scope of this document,
 however, we explain [some background of this model](#background), in an effort
 to explain how we profile its performance. We intend this profiling effort to
 address [issue 42678](https://github.com/rust-lang/rust/issues/42678).
@@ -50,7 +50,7 @@ This command will generate the following files:
 
 - This additional flag will add all timed passes to the output files mentioned
   above, in step 2. As described below, these passes appear visually distinct
-  from the queries in the HTML output (they currently appear as green boxes, via
+  from the queries in the HTML output (they appear as green boxes, via
   CSS).
 
 ### 4. Inspect the output
@@ -86,8 +86,8 @@ The trace of the queries has a formal structure; see
 We style this formal structure as follows:
 
 - **Timed passes:** Green boxes, when present (via `-Z time-passes`), represent
-  _timed passes_ in the compiler. In future versions, these passes may be
-  replaced by queries, explained below.
+  _timed passes_ in the compiler. As of January 2021 these passes are not queries, but may be
+  replaced by queries in future versions.
 - **Labels:** Some green and red boxes are labeled with text. Where they are
   present, the labels give the following information:
   - The [query's _provider_](#queries), sans its _key_ and its _result_, which
@@ -111,7 +111,7 @@ Heuristics-based CSS Classes:
 
 - `important` -- Trace nodes are `important` if they have an extent of 6 (or
   more), _or_ they have a duration fraction of one percent (or more). These
-  numbers are simple heuristics (currently hard-coded, but easy to modify).
+  numbers are simple heuristics (hard-coded, but easy to modify).
   Important nodes are styled with textual labels, and highlighted borders (light
   red, and bolded).
 

src/queries/query-evaluation-model-in-detail.md

@@ -75,11 +75,11 @@ When the query context is created, it is still empty: No queries have been
 executed, no results are cached. But the context already provides access to
 "input" data, i.e. pieces of immutable data that were computed before the
 context was created and that queries can access to do their computations.
-Currently this input data consists mainly of the HIR map, upstream crate
-metadata, and the command-line
-options the compiler was invoked with. In the future, inputs will just consist
-of command-line options and a list of source files -- the HIR map will itself
-be provided by a query which processes these source files.
+
+As of January 2021, this input data consists mainly of the HIR map, upstream crate metadata, and the
+command-line options the compiler was invoked with; but in the future inputs will just consist of
+command-line options and a list of source files -- the HIR map will itself be provided by a query
+which processes these source files.
 
 Without inputs, queries would live in a void without anything to compute their
 result from (remember, query providers only have access to other queries and

src/query.md

@@ -1,7 +1,7 @@
 # Queries: demand-driven compilation
 
 As described in [the high-level overview of the compiler][hl], the
-Rust compiler is currently transitioning from a traditional "pass-based"
+Rust compiler is still (as of January 2021) transitioning from a traditional "pass-based"
 setup to a "demand-driven" system. **The Compiler Query System is the
 key to our new demand-driven organization.** The idea is pretty
 simple. You have various queries that compute things about the input

src/salsa.md

@@ -7,8 +7,10 @@ want to watch [Salsa In More
 Depth](https://www.youtube.com/watch?v=i_IhACacPRY), also by Niko
 Matsakis.
 
-> Salsa is not used directly in rustc, but it is used extensively for
-> rust-analyzer and may be integrated into the compiler in the future.
+> As of January 2021, although Salsa is inspired by (among other things) rustc's query system,
+> it is not used directly in rustc.
+> It _is_ used in chalk and extensively in `rust-analyzer`, but there are no medium or long-term
+> concrete plans to integrate it into the compiler.
 
 ## What is Salsa?
 

src/tests/intro.md

@@ -123,7 +123,7 @@ essence, it runs `./x.py test` after building for each of them.
 
 The integration bot [bors] is used for coordinating merges to the master
 branch. When a PR is approved, it goes into a [queue] where merges are tested
-one at a time on a wide set of platforms using GitHub Actions (currently over
+one at a time on a wide set of platforms using GitHub Actions (as of January 2021 over
 50 different configurations). Due to the limit on the number of parallel jobs,
 we run CI under the [rust-lang-ci] organization except for PRs.
 Most platforms only run the build steps, some run a restricted set of tests,

src/the-parser.md

@@ -1,7 +1,7 @@
 # Lexing and Parsing
 
-> The parser and lexer are currently undergoing a lot of refactoring, so parts
-> of this chapter may be out of date.
+As of January 2021, the lexer and parser are undergoing refactoring to allow
+extracting them into libraries.
 
 The very first thing the compiler does is take the program (in Unicode
 characters) and turn it into something the compiler can work with more

src/traits/chalk.md

@@ -1,9 +1,9 @@
 # Chalk-based trait solving
 
-[Chalk][chalk] is an experimental trait solver for rust that is currently
+[Chalk][chalk] is an experimental trait solver for rust that is (as of January 2021)
 under development by the [Traits Working Group][wg]. Its goal is
 to enable a lot of trait system features and bug fixes that are
-currently hard to implement (e.g. GATs or specialization).  if you 
+hard to implement (e.g. GATs or specialization). If you
 would like to help in hacking on the new solver, you will find
 instructions for getting involved in the
 [Traits Working Group tracking issue][wg].
@@ -28,7 +28,7 @@ You can read more about chalk itself in the
 [Chalk book](https://rust-lang.github.io/chalk/book/) section.
 
 ## Ongoing work
-The design of the new-style trait solving currently happens in two places:
+The design of the new-style trait solving happens in two places:
 
 **chalk**. The [chalk][chalk] repository is where we experiment with new ideas
 and designs for the trait system.

src/traits/lowering-module.md

@@ -1,3 +0,0 @@
-# The lowering module in rustc
-
-This work is ongoing. This section will be filled in once some of it has landed in `rustc`. 

src/traits/resolution.md

@@ -118,7 +118,7 @@ the obligation contains unbound inference variables.
 
 The subroutines that decide whether a particular impl/where-clause/etc
 applies to a particular obligation are collectively referred to as the
-process of _matching_. At the moment, this amounts to
+process of _matching_. As of January 2021, this amounts to
 unifying the `Self` types, but in the future we may also recursively
 consider some of the nested obligations, in the case of an impl.