Merge pull request #273 from mark-i-m/conventions

Update Conventions chapters, add chapter on dependencies

Author: nikomatsakis

src/SUMMARY.md

@@ -20,6 +20,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

@@ -11,7 +11,7 @@ rustc is slowly moving towards the [Rust standard coding style][fmt];
 at the moment, however, it follows a rather more *chaotic* style.  We
 do have some mandatory formatting conventions, which are automatically
 enforced by a script we affectionately call the "tidy" script.  The
-tidy script runs automatically when you do `./x.py test` and can be run 
+tidy script runs automatically when you do `./x.py test` and can be run
 in isolation with `./x.py test src/tools/tidy`.
 
 [fmt]: https://github.com/rust-lang-nursery/fmt-rfcs
@@ -20,11 +20,12 @@ in isolation with `./x.py test src/tools/tidy`.
 
 ### Copyright notice
 
-Some existing files begin with a copyright and license notice. Please omit this
-notice for new files licensed under the standard terms (dual MIT/Apache-2.0).
-For existing files, the year at the top is not meaningful: copyright
-protections are in fact automatic from the moment of authorship. We do not
-typically edit the years on existing files.
+In the past, files begin with a copyright and license notice. Please **omit**
+this notice for new files licensed under the standard terms (dual
+MIT/Apache-2.0).
+
+All of the copyright notices should be gone by now, but if you come across one
+in the rust-lang/rust repo, feel free to open a PR to remove it.
 
 ## Line length
 
@@ -132,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