1 files changed, 83 insertions, 0 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 194a40e15..46ee030fc 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -184,6 +184,27 @@ use crate::{}
 use super::{} // but prefer `use crate::`
 ```
 
+## Import Style
+
+Items from `hir` and `ast` should be used qualified:
+
+```rust
+// Good
+use ra_syntax::ast;
+
+fn frobnicate(func: hir::Function, strukt: ast::StructDef) {}
+
+// Not as good
+use hir::Function;
+use ra_syntax::ast::StructDef;
+
+fn frobnicate(func: Function, strukt: StructDef) {}
+```
+
+Avoid local `use MyEnum::*` imports.
+
+Prefer `use crate::foo::bar` to `use super::bar`.
+
 ## Order of Items
 
 Optimize for the reader who sees the file for the first time, and wants to get the general idea about what's going on.
@@ -220,6 +241,68 @@ struct Foo {
 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 :-)
 
+## Preconditions
+
+Function preconditions should generally be expressed in types and provided by the caller (rather than checked by callee):
+
+```rust
+// Good
+fn frbonicate(walrus: Walrus) {
+  ...
+}
+
+// Not as good
+fn frobnicate(walrus: Option<Walrus>) {
+  let walrus = match walrus {
+    Some(it) => it,
+    None => return,
+  };
+  ...
+}
+```
+
+## Commit Style
+
+We don't have specific rules around git history hygiene.
+Maintaining clean git history is encouraged, but not enforced.
+We use rebase workflow, it's OK to rewrite history during PR review process.
+
+Avoid @mentioning people in commit messages, as such messages create a lot of duplicate notification traffic during rebases.
+
+# Architecture Invariants
+
+This section tries to document high-level design constraints, which are not
+always obvious from the low-level code.
+
+## Incomplete syntax trees
+
+Syntax trees are by design incomplete and do not enforce well-formedness.
+If ast method returns an `Option`, it *can* be `None` at runtime, even if this is forbidden by the grammar.
+
+## LSP indenpendence
+
+rust-analyzer is independent from LSP.
+It provides features for a hypothetical perfect Rust-specific IDE client.
+Internal representations are lowered to LSP in the `rust-analyzer` crate (the only crate which is allowed to use LSP types).
+
+## IDE/Compiler split
+
+There's a semi-hard split between "compiler" and "IDE", at the `ra_hir` crate.
+Compiler derives new facts about source code.
+It explicitly acknowledges that not all info is available (ie, you can't look at types during name resolution).
+
+IDE assumes that all information is available at all times.
+
+IDE should use only types from `ra_hir`, and should not depend on the underling compiler types.
+`ra_hir` is a facade.
+
+## IDE API
+
+The main IDE crate (`ra_ide`) uses "Plain Old Data" for the API.
+Rather than talking in definitions and references, it talks in Strings and textual offsets.
+In general, API is centered around UI concerns -- the result of the call is what the user sees in the editor, and not what the compiler sees underneath.
+The results are 100% Rust specific though.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to