3 files changed, 50 insertions, 10 deletions

diff --git a/docs/dev/README.md b/docs/dev/README.md
index ad18217f1..36edddc70 100644
--- a/docs/dev/README.md
+++ b/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).
diff --git a/docs/dev/lsp-extensions.md b/docs/dev/lsp-extensions.md
index 1be01fd88..2e3133449 100644
--- a/docs/dev/lsp-extensions.md
+++ b/docs/dev/lsp-extensions.md
@@ -412,7 +412,13 @@ Reloads project information (that is, re-executes `cargo metadata`).
 
 **Method:** `rust-analyzer/status`
 
-**Notification:** `"loading" | "ready" | "invalid" | "needsReload"`
+**Notification:**
+
+```typescript
+interface StatusParams {
+    status: "loading" | "ready" | "invalid" | "needsReload",
+}
+```
 
 This notification is sent from server to client.
 The client can use it to display persistent status to the user (in modline).
diff --git a/docs/dev/style.md b/docs/dev/style.md
index 3bbab6da9..8effddcda 100644
--- a/docs/dev/style.md
+++ b/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,36 @@ fn frobnicate(walrus: Option<Walrus>) {
 }
 ```
 
-## Premature Pessimization
+# Getters & Setters
+
+If a field can have any value without breaking invariants, make the field public.
+Conversely, if there is an invariant, document it, enforce it in the "constructor" function, make the field private, and provide a getter.
+Never provide setters.
+
+Getters should return borrowed data:
+
+```
+struct Person {
+    // Invariant: never empty
+    first_name: String,
+    middle_name: Option<String>
+}
+
+// Good
+impl Person {
+    fn first_name(&self) -> &str { self.first_name.as_str() }
+    fn middle_name(&self) -> Option<&str> { self.middle_name.as_ref() }
+}
+
+// Not as good
+impl Person {
+    fn first_name(&self) -> String { self.first_name.clone() }
+    fn middle_name(&self) -> &Option<String> { &self.middle_name }
+}
+```
+
+
+# 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 +226,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.