From 200161c734e996e68f74d242d96d89b561a6dd17 Mon Sep 17 00:00:00 2001 From: Aleksey Kladov Date: Fri, 14 Aug 2020 12:27:15 +0200 Subject: Document the most important CI invariant --- docs/dev/README.md | 5 +++++ docs/dev/style.md | 18 +++++++++--------- 2 files changed, 14 insertions(+), 9 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/style.md b/docs/dev/style.md index 3bbab6da9..963a6d73d 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,7 @@ fn frobnicate(walrus: Option) { } ``` -## 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. -- cgit v1.2.3