update conventions

src/SUMMARY.md

@@ -19,6 +19,7 @@
 - [Profiling the compiler](./profiling.md)
     - [with the linux perf tool](./profiling/with_perf.md)
 - [Coding conventions](./conventions.md)
+- [crates.io Dependencies](./crates-io.md)
 
 ---
 

src/conventions.md

@@ -133,3 +133,18 @@ require that every intermediate commit successfully builds – we only
 expect to be able to bisect at a PR level. However, if you *can* make
 individual commits build, that is always helpful.
 
+# Naming conventions
+
+Apart from normal Rust style/naming conventions, there are also some specific
+to the compiler.
+
+- `cx` tends to be short for "context" and is often used as a suffix. For
+  example, `tcx` is a common name for the [Typing Context][tcx].
+
+- [`'tcx` and `'gcx`][tcx] are used as the lifetime names for the Typing
+  Context.
+
+- Because `crate` is a keyword, if you need a variable to represent something
+  crate-related, often the spelling is changed to `krate`.
+
+[tcx]: ./ty.md

src/crates-io.md

@@ -0,0 +1,23 @@
+# crates.io Dependencies
+
+The rust compiler supports building with some dependencies from `crates.io`.
+For example, `log` and `env_logger` come from `crates.io`.
+
+In general, you should avoid adding dependencies to the compiler for several
+reasons:
+
+- The dependency may not be high quality or well-maintained, whereas we want
+  the compiler to be high-quality.
+- The dependency may not be using a compatible license.
+- The dependency may have transitive dependencies that have one of the above
+  problems.
+
+TODO: what is the vetting process?
+
+## Whitelist
+
+The `tidy` tool has a [whitelist] of crates that are allowed. To add a
+dependency that is not already in the compiler, you will need to add it to this
+whitelist.
+
+[whitelist]: https://github.com/rust-lang/rust/blob/659994627234ce7d95a1a52ad8756ce661059adf/src/tools/tidy/src/deps.rs#L56