From ae1acbd09c8e98e4e23f01f633ad551dabd5c578 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Sat, 6 Jun 2020 19:32:45 +0200
Subject: [PATCH 1/2] Document import style

---
 docs/dev/README.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 194a40e15c42..6f74d42236d4 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.

From 81ffe973ac265507419024048c166bbeef9aa275 Mon Sep 17 00:00:00 2001
From: Aleksey Kladov <aleksey.kladov@gmail.com>
Date: Sat, 6 Jun 2020 19:54:41 +0200
Subject: [PATCH 2/2] Document certain invariants

---
 docs/dev/README.md | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/docs/dev/README.md b/docs/dev/README.md
index 6f74d42236d4..903cb4055a83 100644
--- a/docs/dev/README.md
+++ b/docs/dev/README.md
@@ -241,6 +241,33 @@ 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 :-)
 
+# 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.
+
 # Logging
 
 Logging is done by both rust-analyzer and VS Code, so it might be tricky to