2 files changed, 79 insertions, 2 deletions
diff --git a/src/doc/style-guide/src/cargo.md b/src/doc/style-guide/src/cargo.md
index f4993ba06..13b96ca8c 100644
--- a/src/doc/style-guide/src/cargo.md
+++ b/src/doc/style-guide/src/cargo.md
@@ -17,8 +17,7 @@ followed by the `description` at the end of that section.
 Don't use quotes around any standard key names; use bare keys. Only use quoted
 keys for non-standard keys whose names require them, and avoid introducing such
 key names when possible.  See the [TOML
-specification](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md#table)
-for details.
+specification](https://toml.io/en/v1.0.0#keys) for details.
 
 Put a single space both before and after the `=` between a key and value. Do
 not indent any key names; start all key names at the start of a line.
diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md
index 29b48bb1e..4ab1c36f9 100644
--- a/src/doc/style-guide/src/statements.md
+++ b/src/doc/style-guide/src/statements.md
@@ -99,6 +99,84 @@ let Foo {
 );
 ```
 
+#### else blocks (let-else statements)
+
+If a let statement contains an `else` component, also known as a let-else statement,
+then the `else` component should be formatted according to the same rules as the `else` block
+in [control flow expressions (i.e. if-else, and if-let-else expressions)](./expressions.md#control-flow-expressions).
+Apply the same formatting rules to the components preceding
+the `else` block (i.e. the `let pattern: Type = initializer_expr ...` portion)
+as described [above](#let-statements)
+
+Similarly to if-else expressions, if the initializer
+expression is multi-lined, then the `else` keyword and opening brace of the block (i.e. `else {`)
+should be put on the same line as the end of the initializer
+expression with a preceding space if all the following are true:
+
+* The initializer expression ends with one or more closing
+  parentheses, square brackets, and/or braces
+* There is nothing else on that line
+* That line is not indented beyond the indent of the first line containing the `let` keyword
+
+For example:
+
+```rust
+let Some(x) = y.foo(
+    "abc",
+    fairly_long_identifier,
+    "def",
+    "123456",
+    "string",
+    "cheese",
+) else {
+    bar()
+}
+```
+
+Otherwise, the `else` keyword and opening brace should be placed on the next line after the end of the initializer expression, and should not be indented (the `else` keyword should be aligned with the `let` keyword).
+
+For example:
+
+```rust
+let Some(x) = abcdef()
+    .foo(
+        "abc",
+        some_really_really_really_long_ident,
+        "ident",
+        "123456",
+    )
+    .bar()
+    .baz()
+    .qux("fffffffffffffffff")
+else {
+    foo_bar()
+}
+```
+
+##### Single line let-else statements
+
+The entire let-else statement may be formatted on a single line if all the following are true:
+
+* the entire statement is *short*
+* the `else` block contains a single-line expression and no statements
+* the `else` block contains no comments
+* the let statement components preceding the `else` block can be formatted on a single line
+
+```rust
+let Some(1) = opt else { return };
+
+let Some(1) = opt else {
+    return;
+};
+
+let Some(1) = opt else {
+    // nope
+    return
+};
+```
+
+Formatters may allow users to configure the value of the threshold
+used to determine whether a let-else statement is *short*.
 
 ### Macros in statement position