Document the most important CI invariant

docs/dev/README.md

@@ -165,6 +165,11 @@ In general, API is centered around UI concerns -- the result of the call is what
 The results are 100% Rust specific though.
 Shout outs to LSP developers for popularizing the idea that "UI" is a good place to draw a boundary at.
 
+## CI
+
+CI does not test rust-analyzer, CI is a core part of rust-analyzer, and is maintained with above average standard of quality.
+CI is reproducible -- it can only be broken by changes to files in this repository, any dependence on externalities is a bug.
+
 # Code Style & Review Process
 
 Do see [./style.md](./style.md).

docs/dev/style.md

@@ -65,7 +65,7 @@ There are many benefits to this:
 It also makes sense to format snippets more compactly (for example, by placing enum definitions like `enum E { Foo, Bar }` on a single line),
 as long as they are still readable.
 
-## Order of Imports
+# Order of Imports
 
 Separate import groups with blank lines.
 Use one `use` per crate.
@@ -91,7 +91,7 @@ use super::{}
 Module declarations come before the imports.
 Order them in "suggested reading order" for a person new to the code base.
 
-## Import Style
+# Import Style
 
 Qualify items from `hir` and `ast`.
 
@@ -112,7 +112,7 @@ Avoid local `use MyEnum::*` imports.
 
 Prefer `use crate::foo::bar` to `use super::bar`.
 
-## Order of Items
+# Order of Items
 
 Optimize for the reader who sees the file for the first time, and wants to get a general idea about what's going on.
 People read things from top to bottom, so place most important things first.
@@ -143,7 +143,7 @@ struct Foo {
 }
 ```
 
-## Variable Naming
+# Variable Naming
 
 Use boring and long names for local variables ([yay code completion](https://github.com/rust-analyzer/rust-analyzer/pull/4162#discussion_r417130973)).
 The default name is a lowercased name of the type: `global_state: GlobalState`.
@@ -151,12 +151,12 @@ Avoid ad-hoc acronyms and contractions, but use the ones that exist consistently
 The default name for "result of the function" local variable is `res`.
 The default name for "I don't really care about the name" variable is `it`.
 
-## Collection types
+# Collection types
 
 Prefer `rustc_hash::FxHashMap` and `rustc_hash::FxHashSet` instead of the ones in `std::collections`.
 They use a hasher that's slightly faster and using them consistently will reduce code size by some small amount.
 
-## Preconditions
+# Preconditions
 
 Express function preconditions in types and force the caller to provide them (rather than checking in callee):
 
@@ -176,7 +176,7 @@ fn frobnicate(walrus: Option<Walrus>) {
 }
 ```
 
-## Premature Pessimization
+# Premature Pessimization
 
 Avoid writing code which is slower than it needs to be.
 Don't allocate a `Vec` where an iterator would do, don't allocate strings needlessly.
@@ -197,12 +197,12 @@ if words.len() != 2 {
 }
 ```
 
-## Documentation
+# Documentation
 
 For `.md` and `.adoc` files, prefer a sentence-per-line format, don't wrap lines.
 If the line is too long, you want to split the sentence in two :-)
 
-## Commit Style
+# Commit Style
 
 We don't have specific rules around git history hygiene.
 Maintaining clean git history is encouraged, but not enforced.