Reorganise and clean up the whole guide.

book.toml

@@ -22,3 +22,6 @@ renderer = ["html"]
 git-repository-icon = "fa-github"
 git-repository-url = "https://github.com/rust-lang/std-dev-guide"
 edit-url-template = "https://github.com/rust-lang/std-dev-guide/edit/master/{path}"
+
+[output.html.redirect]
+"/feature-lifecycle/stabilization.html" = "/development/stabilization.html"

src/SUMMARY.md

@@ -1,60 +1,30 @@
 # Summary
 
-[About this guide](./about-this-guide.md)
-
-[Getting started](./getting-started.md)
-
-- [The library team](./team.md)
-  - [Meetings](./meetings.md)
-  - [Membership](./membership.md)
-  - [Reviewing](./reviewing.md)
-
----
-
-- [Building and debugging libraries](./development/building-and-debugging.md)
-- [Performance optimizations and benchmarking](./development/perf-benchmarking.md)
-
-
----
-
-- [The feature lifecycle](./feature-lifecycle/summary.md)
-    - [API Change Proposals](./feature-lifecycle/api-change-proposals.md)
-    - [Using tracking issues](./feature-lifecycle/tracking-issues.md)
-    - [Stabilizing features](./feature-lifecycle/stabilization.md)
-    - [Deprecating features](./feature-lifecycle/deprecation.md)
-
----
-
-- [Code considerations](./code-considerations/summary.md)
-    - [Design](./code-considerations/design/summary.md)
-        - [Public APIs](./code-considerations/design/public-apis.md)
-        - [When to add `#[must_use]`](./code-considerations/design/must-use.md)
-    - [Breaking changes](./code-considerations/breaking-changes/summary.md)
-        - [Breakage from changing behavior](./code-considerations/breaking-changes/behavior.md)
-        - [Breakage from new trait impls](./code-considerations/breaking-changes/new-trait-impls.md)
-        - [`#[fundamental]` types](./code-considerations/breaking-changes/fundamental.md)
-        - [Breakage from changing the prelude](./code-considerations/breaking-changes/prelude.md)
-    - [Safety and soundness](./code-considerations/safety-and-soundness/summary.md)
-        - [Generics and unsafe](./code-considerations/safety-and-soundness/generics-and-unsafe.md)
-        - [Drop and `#[may_dangle]`](./code-considerations/safety-and-soundness/may-dangle.md)
-        - [`std::mem` and exclusive references](./code-considerations/safety-and-soundness/mem-and-exclusive-refs.md)
-    - [Using unstable language features](./code-considerations/using-unstable-lang/summary.md)
-        - [Const generics](./code-considerations/using-unstable-lang/const-generics.md)
-        - [Specialization](./code-considerations/using-unstable-lang/specialization.md)
-    - [Performance](./code-considerations/performance/summary.md)
-        - [When to `#[inline]`](./code-considerations/performance/inline.md)
-
----
-
-- [Documentation](./documentation/summary.md)
-    - [doc alias policy](./documentation/doc-alias-policy.md)
-    - [safety comments policy](./documentation/safety-comments.md)
-    - [how to write documentation](./documentation/how-to-write-documentation.md)
-    - [reviewing doc changes](./documentation/reviewing-doc-changes.md)
-
----
-
-- [Tools and bots](./tools-and-bots/summary.md)
-    - [`@bors`](./tools-and-bots/bors.md)
-    - [`@rust-timer`](./tools-and-bots/timer.md)
-    - [`@craterbot`](./tools-and-bots/crater.md)
+- [About this Guide](about.md)
+
+- [Contributing to the standard libraries]()
+    - [Building and debugging](./development/building-and-debugging.md)
+    - [Performance optimizations and benchmarking](./development/perf-benchmarking.md)
+    - [Writing documentation](./development/how-to-write-documentation.md)
+    - [Stabilizing a feature](./development/stabilization.md)
+
+- [Breaking changes](./breaking-changes/summary.md)
+    - [New trait implementations](./breaking-changes/new-trait-impls.md)
+    - [Prelude](./breaking-changes/prelude.md)
+    - [Doc changes](./breaking-changes/doc-changes.md)
+
+- [Policies]()
+    - [When to add `#[must_use]`](./policy/must-use.md)
+    - [Specialization](./policy/specialization.md)
+    - [When to `#[inline]`](./policy/inline.md)
+    - [Doc alias policy](./policy/doc-alias.md)
+    - [Safety comments policy](./policy/safety-comments.md)
+
+- [Tricky situations]()
+    - [Drop and `#[may_dangle]`](./tricky/may-dangle.md)
+    - [Generics and unsafe](./tricky/generics-and-unsafe.md)
+
+- [The library team](./team/summary.md)
+    - [Meetings](./team/meetings.md)
+    - [Membership](./team/membership.md)
+    - [Reviewing](./team/reviewing.md)

src/about.md

@@ -0,0 +1,13 @@
+# About this Guide
+
+Welcome to the std dev guide.
+
+This guide is maintained by the library team.
+
+The guide is not very complete yet.
+Contributions to this guide are very welcome.
+
+Other useful documentation:
+
+- https://forge.rust-lang.org/
+- https://rustc-dev-guide.rust-lang.org/

src/documentation/reviewing-doc-changes.md → src/breaking-changes/doc-changes.md

@@ -1,13 +1,4 @@
-# Reviewing doc changes
-
-Most of the time, it is mostly reviewing that the documentation isn't wrong
-in any way and that it follows the
-[how to write documentation](./how-to-write-documentation.md) guideline.
-
-There is however something where we need to be extra careful: stability
-guarantees.
-
-## Stability guarantees
+# Breaking documentation changes
 
 First, short explanation about what a stability guarantee is: a statement in
 the document which explains what the item is doing in a precise case. For

src/breaking-changes/new-trait-impls.md

@@ -0,0 +1,93 @@
+# Breakage from new trait impls
+
+A lot of PRs to the standard library are adding new impls for already stable traits,
+which can break consumers in many weird and wonderful ways.
+Below are some examples of breakage from new trait impls that
+may not be obvious just from the change made to the standard library.
+
+## Inference breaks when a second generic impl is introduced
+
+Rust will use the fact that there's only a single impl for a generic trait during inference.
+This breaks once a second impl makes the type of that generic ambiguous.
+Say we have:
+
+```rust,ignore
+// in `std`
+impl From<&str> for Arc<str> { .. }
+```
+
+```rust,ignore
+// in an external `lib`
+let b = Arc::from("a");
+```
+
+then we add:
+
+```diff
+impl From<&str> for Arc<str> { .. }
++ impl From<&str> for Arc<String> { .. }
+```
+
+then
+
+```rust,ignore
+let b = Arc::from("a");
+```
+
+will no longer compile, because we've previously been relying on inference to figure out the `T` in `Box<T>`.
+
+This kind of breakage can be ok, but a [crater](https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md) run should estimate the scope.
+
+## Deref coercion breaks when a new impl is introduced
+
+Rust will use deref coercion to find a valid trait impl if the arguments don't type check directly.
+This only seems to occur if there's a single impl so introducing a new one may break consumers relying on deref coercion.
+Say we have:
+
+```rust,ignore
+// in `std`
+impl Add<&str> for String { .. }
+
+impl Deref for String { type Target = str; .. }
+```
+
+```rust,ignore
+// in an external `lib`
+let a = String::from("a");
+let b = String::from("b");
+
+let c = a + &b;
+```
+
+then we add:
+
+```diff,ignore
+  impl Add<&str> for String { .. }
++ impl Add<char> for String { .. }
+```
+
+then
+
+```rust,ignore
+let c = a + &b;
+```
+
+will no longer compile, because we won't attempt to use deref to coerce the `&String` into `&str`.
+
+This kind of breakage can be ok, but a [crater](https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md) run should estimate the scope.
+
+## `#[fundamental]` types
+
+Type annotated with the `#[fundamental]` attribute have different coherence rules.
+See [RFC 1023](https://rust-lang.github.io/rfcs/1023-rebalancing-coherence.html) for details.
+That includes:
+
+- `&T`
+- `&mut T`
+- `Box<T>`
+- `Pin<T>`
+
+Typically, the scope of breakage in new trait impls is limited to inference and deref-coercion.
+New trait impls on `#[fundamental]` types may overlap with downstream impls and cause other kinds of breakage.
+
+[RFC 1023]: https://rust-lang.github.io/rfcs/1023-rebalancing-coherence.html

src/code-considerations/breaking-changes/prelude.md → src/breaking-changes/prelude.md

@@ -1,15 +1,18 @@
 # Breaking changes to the prelude
 
-Making changes to the prelude can easily cause breakage because it impacts all Rust code. In most cases the impact is limited since prelude items have the lowest priority in name lookup (lower than glob imports), but there are two cases where this doesn't work.
+Making changes to the prelude can easily cause breakage because it impacts all Rust code.
+In most cases the impact is limited since prelude items have the lowest priority in name lookup (lower than glob imports), but there are two cases where this doesn't work.
 
 ## Traits
 
-Adding a new trait to the prelude causes new methods to become available for existing types. This can cause name resolution errors in user code if a method with the same name is also available from a different trait.
+Adding a new trait to the prelude causes new methods to become available for existing types.
+This can cause name resolution errors in user code if a method with the same name is also available from a different trait.
 
 For this reason, [`TryFrom` and `TryInto`](https://github.com/rust-lang/rust/issues/33417) were only added to the prelude for the 2021 edition despite being stabilized in 2019.
 
 ## Macros
 
-Unlike other item types, rustc's name resolution for macros does not support giving prelude macros a lower priority than other macros, even if the macro is unstable. As a general rule, avoid adding macros to the prelude except at edition boundaries.
+Unlike other item types, rustc's name resolution for macros does not support giving prelude macros a lower priority than other macros, even if the macro is unstable.
+As a general rule, avoid adding macros to the prelude except at edition boundaries.
 
 This issues was encoutered when trying to land the [`assert_matches!` macro](https://github.com/rust-lang/rust/issues/82913).

src/breaking-changes/summary.md

@@ -0,0 +1,8 @@
+# Breaking changes
+
+Breaking changes should be avoided when possible.
+[RFC 1105](https://rust-lang.github.io/rfcs/1105-api-evolution.html) lays the foundations for what constitutes a breaking change.
+Breakage may be deemed acceptable or not based on its actual impact,
+which can be approximated with a [crater](https://github.com/rust-lang/crater/blob/master/docs/bot-usage.md) run.
+
+If the impact isn't too high, looping in maintainers of broken crates and submitting PRs to fix them can be a valid strategy.