tidy up sections

KodrAus · KodrAus · commit 3931fb4feada · 2021-01-29T15:09:51.000+10:00
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -23,7 +23,7 @@
     - [New trait impls](./code-considerations/breaking-changes/new-trait-impls.md)
     - [`#[fundamental]` types](./code-considerations/breaking-changes/fundamental.md)
 - [Safety and soundness](./code-considerations/safety-and-soundness/summary.md)
-    - [Generic impls and soundness](./code-considerations/safety-and-soundness/generic-impls-and-soundness.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)
@@ -32,6 +32,8 @@
 - [Performance](./code-considerations/performance/summary.md)
     - [When to `#[inline]`](./code-considerations/performance/inline.md)
 
----
+# Tools and bots
 
-[Appendix A: Glossary](./appendix/glossary.md)
+- [`@bors`](./tools-and-bots/bors.md)
+- [`@rust-timer`](./tools-and-bots/timer.md)
+- [`@craterbot`](./tools-and-bots/crater.md)
diff --git a/src/appendix/glossary.md b/src/appendix/glossary.md
diff --git a/src/code-considerations/breaking-changes/behavior.md b/src/code-considerations/breaking-changes/behavior.md
@@ -1,6 +1,6 @@
 # Breakage from changing behavior
 
-Breaking changes aren't just limited to compilation failures. Behavioral changes to stable functions generally can't be accepted. See [the `home_dir` issue][rust/pull/46799] for an example.
+Breaking changes aren't just limited to compilation failures. Behavioral changes to stable functions generally can't be accepted. See [the `home_dir` issue](https://github.com/rust-lang/rust/pull/46799) for an example.
 
 An exception is when a behavior is specified in an RFC (such as IETF specifications for IP addresses). If a behavioral change fixes non-conformance then it can be considered a bug fix. In these cases, `@rust-lang/libs` should still be pinged for input.
 
diff --git a/src/code-considerations/breaking-changes/fundamental.md b/src/code-considerations/breaking-changes/fundamental.md
@@ -2,7 +2,7 @@
 
 **Status:** Stub
 
-Type annotated with the `#[fundamental]` attribute have different coherence rules. See [RFC 1023] for details. That includes:
+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`
@@ -28,4 +28,4 @@ where
 
 unless the blanket implementation is being stabilized along with `PublicTrait`. In cases where we really want to do this, a [crater] run can help estimate the scope of the breakage.
 
-[crater]: ./crater.md
+[crater]: ../../tools-and-bots/crater.md
diff --git a/src/code-considerations/breaking-changes/new-trait-impls.md b/src/code-considerations/breaking-changes/new-trait-impls.md
@@ -67,9 +67,7 @@ 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] run should estimate the scope.
-
-[crater]: ./crater.md
+This kind of breakage can be ok, but a [crater](../../tools-and-bots/crater.md) run should estimate the scope.
 
 ## For reviewers
 
diff --git a/src/code-considerations/breaking-changes/summary.md b/src/code-considerations/breaking-changes/summary.md
@@ -1,6 +1,6 @@
 # Breaking changes
 
-Breaking changes should be avoided when possible. [RFC 1105] 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] run.
+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](../../tools-and-bots/crater.md) run.
 
 There are strategies for mitigating breakage depending on the impact.
 
@@ -12,9 +12,6 @@ If the impact isn't too high:
 
 - Looping in maintainers of broken crates and submitting PRs to fix them.
 
-[crater]: ./crater.md
-[RFC 1105]: https://rust-lang.github.io/rfcs/1105-api-evolution.html
-
 ## For reviewers
 
 Look out for changes to documented behavior and new trait impls for existing stable traits.
diff --git a/src/code-considerations/design/public-apis.md b/src/code-considerations/design/public-apis.md
@@ -2,9 +2,7 @@
 
 **Status:** Stub
 
-Standard library APIs typically follow the [API Guidelines], which were originally spawned from the standard library itself.
-
-[API Guidelines]: https://rust-lang.github.io/api-guidelines/
+Standard library APIs typically follow the [API Guidelines](https://rust-lang.github.io/api-guidelines/), which were originally spawned from the standard library itself.
 
 ## For reviewers
 
diff --git a/src/code-considerations/performance/inline.md b/src/code-considerations/performance/inline.md
@@ -1,8 +1,8 @@
 # When to `#[inline]`
 
-Inlining is a trade-off between potential execution speed, compile time and code size. There's some discussion about it in [this PR to the `hashbrown` crate][hashbrown/pull/119]. From the thread:
+Inlining is a trade-off between potential execution speed, compile time and code size. There's some discussion about it in [this PR to the `hashbrown` crate](https://github.com/rust-lang/hashbrown/pull/119). From the thread:
 
-> `#[inline]` is very different than simply just an inline hint. As I mentioned before, there's no equivalent in C++ for what `#[inline]` does. In debug mode rustc basically ignores `#[inline]`, pretending you didn't even write it. In release mode the compiler will, by default, codegen an `#[inline]` function into every single referencing codegen unit, and then it will also add `inlinehin`t. This means that if you have 16 CGUs and they all reference an item, every single one is getting the entire item's implementation inlined into it.
+> `#[inline]` is very different than simply just an inline hint. As I mentioned before, there's no equivalent in C++ for what `#[inline]` does. In debug mode rustc basically ignores `#[inline]`, pretending you didn't even write it. In release mode the compiler will, by default, codegen an `#[inline]` function into every single referencing codegen unit, and then it will also add `inlinehint`. This means that if you have 16 CGUs and they all reference an item, every single one is getting the entire item's implementation inlined into it.
 
 You can add `#[inline]`:
 
diff --git a/src/code-considerations/performance/summary.md b/src/code-considerations/performance/summary.md
@@ -2,10 +2,8 @@
 
 **Status:** Stub
 
-Changes to hot code might impact performance in consumers, for better or for worse. Appropriate benchmarks should give an idea of how performance characteristics change. For changes that affect `rustc` itself, you can also do a [`rust-timer`] run.
+Changes to hot code might impact performance in consumers, for better or for worse. Appropriate benchmarks should give an idea of how performance characteristics change. For changes that affect `rustc` itself, you can also do a [`rust-timer`](../../tools-and-bots/timer.md) run.
 
 ## For reviewers
 
 If a PR is focused on performance then try get some idea of what the impact is. Also consider marking the PR as `rollup=never`.
-
-[`rust-timer`]: https://github.com/rust-lang-nursery/rustc-perf
diff --git a/src/code-considerations/reviewer-checklist.md b/src/code-considerations/reviewer-checklist.md
@@ -2,28 +2,28 @@
 
 **Status:** Stub
 
-## Before you review
-
-Check the [getting started](./getting-started.md) guide for an introduction to developing in the standard library.
+Check the [getting started](../getting-started.md) guide for an introduction to developing in the standard library.
 
 If you'd like to reassign the PR, you can:
 
 ```
 r? @user
 ```
 
+## Before you review
+
 - [ ] Are there any `#[stable]` attributes involved?
     - [ ] Ping `@rust-lang/libs` for input.
 
 ## As you review
 
-Look out for:
+Look out for code considerations:
 
-- [ ] [Breaking changes](./code-considerations/breaking-changes/summary.md)
-- [ ] [Safety and soundness](./code-considerations/safety-and-soundness/summary.md)
-- [ ] [Quality](./code-considerations/quality/summary.md)
-- [ ] [Use of unstable language features](./code-considerations/using-unstable-lang/summary.md)
-- [ ] [Performance](./code-considerations/performance/summary.md)
+- [ ] [Design](./design/summary.md)
+- [ ] [Breaking changes](./breaking-changes/summary.md)
+- [ ] [Safety and soundness](./safety-and-soundness/summary.md)
+- [ ] [Use of unstable language features](./using-unstable-lang/summary.md)
+- [ ] [Performance](./performance/summary.md)
 
 ## Before you merge
 
@@ -35,7 +35,7 @@ Look out for:
 
 ## When you're ready
 
-For Libs PRs, rolling up is usually fine, in particular if it's only a new unstable addition or if it only touches docs. See the [rollup guidelines] for more details on when to rollup.
+For Libs PRs, rolling up is usually fine, in particular if it's only a new unstable addition or if it only touches docs. See the [rollup guidelines](https://forge.rust-lang/org/compiler/reviews.md#rollups) for more details on when to rollup.
 
 To roll up:
 
@@ -48,5 +48,3 @@ or just:
 ```
 @bors r+
 ```
-
-[rollup guidelines]: https://forge.rust-lang/org/compiler/reviews.md#rollups
diff --git a/src/code-considerations/safety-and-soundness/generics-and-unsafe.md b/src/code-considerations/safety-and-soundness/generics-and-unsafe.md
@@ -1,4 +1,4 @@
-# Relying on generic trait impls for soundness
+# Generics and unsafe
 
 Be careful of generic types that interact with unsafe code. Unless the generic type is bounded by an unsafe trait that specifies its contract, we can't rely on the results of generic types being reliable or correct.
 
diff --git a/src/code-considerations/safety-and-soundness/may-dangle.md b/src/code-considerations/safety-and-soundness/may-dangle.md
@@ -1,8 +1,8 @@
 # Drop and `#[may_dangle]`
 
-A generic `Type<T>` that manually implements `Drop` should consider whether a `#[may_dangle]` attribute is appropriate on `T`. The [Nomicon][dropck] has some details on what `#[may_dangle]` is all about.
+A generic `Type<T>` that manually implements `Drop` should consider whether a `#[may_dangle]` attribute is appropriate on `T`. The [Nomicon](https://doc.rust-lang.org/nomicon/dropck.html) has some details on what `#[may_dangle]` is all about.
 
-If a generic `Type<T>` has a manual drop implementation that may also involve dropping `T` then dropck needs to know about it. If `Type<T>`'s ownership of `T` is expressed through types that don't drop `T` themselves such as `ManuallyDrop<T>`, `*mut T`, or `MaybeUninit<T>` then `Type<T>` also [needs a `PhantomData<T>` field][RFC 0769 PhantomData] to tell dropck that `T` may be dropped. Types in the standard library that use the internal `Unique<T>` pointer type don't need a `PhantomData<T>` marker field. That's taken care of for them by `Unique<T>`.
+If a generic `Type<T>` has a manual drop implementation that may also involve dropping `T` then dropck needs to know about it. If `Type<T>`'s ownership of `T` is expressed through types that don't drop `T` themselves such as `ManuallyDrop<T>`, `*mut T`, or `MaybeUninit<T>` then `Type<T>` also [needs a `PhantomData<T>` field](https://rust-lang.github.io/rfcs/0769-sound-generic-drop.html#phantom-data) to tell dropck that `T` may be dropped. Types in the standard library that use the internal `Unique<T>` pointer type don't need a `PhantomData<T>` marker field. That's taken care of for them by `Unique<T>`.
 
 As a real-world example of where this can go wrong, consider an `OptionCell<T>` that looks something like this:
 
@@ -36,9 +36,6 @@ struct OptionCell<T> {
 + unsafe impl<#[may_dangle] T> Drop for OptionCell<T> {
 ```
 
-[dropck]: https://doc.rust-lang.org/nomicon/dropck.html
-[RFC 0769 PhantomData]: https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data
-
 ## For reviewers
 
 If there's a manual `Drop` implementation, consider whether `#[may_dangle]` is appropriate. If it is, make sure there's a `PhantomData<T>` too either through `Unique<T>` or manually.
diff --git a/src/code-considerations/safety-and-soundness/mem-and-exclusive-refs.md b/src/code-considerations/safety-and-soundness/mem-and-exclusive-refs.md
@@ -6,11 +6,9 @@ Any value behind a `&mut` reference can be replaced with a new one using `mem::r
 
 ## `mem::forget`
 
-Rust doesn't guarantee destructors will run when a value is leaked (which can be done with `mem::forget`), so code should avoid relying on them for maintaining safety. Remember, [everyone poops][Everyone Poops].
+Rust doesn't guarantee destructors will run when a value is leaked (which can be done with `mem::forget`), so code should avoid relying on them for maintaining safety. Remember, [everyone poops](http://cglab.ca/~abeinges/blah/everyone-poops).
 
-It's ok not to run a destructor when a value is leaked because its storage isn't deallocated or repurposed. If the storage is initialized and is being deallocated or repurposed then destructors need to be run first, because [memory may be pinned][Drop guarantee]. Having said that, there can still be exceptions for skipping destructors when deallocating if you can guarantee there's never pinning involved.
-
-[Drop guarantee]: https://doc.rust-lang.org/nightly/std/pin/index.html#drop-guarantee
+It's ok not to run a destructor when a value is leaked because its storage isn't deallocated or repurposed. If the storage is initialized and is being deallocated or repurposed then destructors need to be run first, because [memory may be pinned](https://doc.rust-lang.org/nightly/std/pin/index.html#drop-guarantee). Having said that, there can still be exceptions for skipping destructors when deallocating if you can guarantee there's never pinning involved.
 
 ## For reviewers
 
diff --git a/src/code-considerations/safety-and-soundness/summary.md b/src/code-considerations/safety-and-soundness/summary.md
@@ -2,13 +2,10 @@
 
 **Status:** Stub
 
-Unsafe code blocks in the standard library need a comment explaining why they're [ok](https://doc.rust-lang.org/nomicon). There's a [tidy] lint that checks this. The unsafe code also needs to actually be ok.
+Unsafe code blocks in the standard library need a comment explaining why they're [ok](https://doc.rust-lang.org/nomicon). There's a lint that checks this. The unsafe code also needs to actually be ok.
 
-The rules around what's sound and what's not can be subtle. See the [Unsafe Code Guidelines WG] for current thinking, and consider pinging `@rust-lang/libs-impl`, `@rust-lang/lang`, and/or somebody from the WG if you're in _any_ doubt. We love debating the soundness of unsafe code, and the more eyes on it the better!
+The rules around what's sound and what's not can be subtle. See the [Unsafe Code Guidelines WG](https://github.com/rust-lang/unsafe-code-guidelines) for current thinking, and consider pinging `@rust-lang/libs-impl`, `@rust-lang/lang`, and/or somebody from the WG if you're in _any_ doubt. We love debating the soundness of unsafe code, and the more eyes on it the better!
 
 ## For reviewers
 
 Look out for any unsafe blocks. If they're optimizations consider whether they're actually necessary. If the unsafe code is necessary then always feel free to ping somebody to help review it.
-
-[tidy]: ./tidy.md
-[Unsafe Code Guidelines WG]: https://github.com/rust-lang/unsafe-code-guidelines
diff --git a/src/code-considerations/using-unstable-lang/const-generics.md b/src/code-considerations/using-unstable-lang/const-generics.md
@@ -2,7 +2,9 @@
 
 **Status:** Stub
 
-Const generics are ok to use in public APIs, so long as they fit in the [`min_const_generics` subset](https://github.com/rust-lang/rust/pull/79135).
+Complete const generics are currently unstable. You can track their progress [here](https://github.com/rust-lang/rust/issues/44580).
+
+Const generics are ok to use in public APIs, so long as they fit in the [`min_const_generics` subset](https://github.com/rust-lang/rust/issues/74878).
 
 ## For reviewers
 
diff --git a/src/code-considerations/using-unstable-lang/specialization.md b/src/code-considerations/using-unstable-lang/specialization.md
@@ -1,6 +1,6 @@
 # Using specialization
 
-Specialization is currently unstable. You can track its progress [here][rust/issues/31844].
+Specialization is currently unstable. You can track its progress [here](https://github.com/rust-lang/rust/issues/31844).
 
 We try to avoid leaning on specialization too heavily, limiting its use to optimizing specific implementations. These specialized optimizations use a private trait to find the correct implementation, rather than specializing the public method itself. Any use of specialization that changes how methods are dispatched for external callers should be carefully considered.
 
diff --git a/src/code-considerations/using-unstable-lang/summary.md b/src/code-considerations/using-unstable-lang/summary.md
@@ -2,8 +2,8 @@
 
 The standard library codebase is a great place to try unstable language features, but we have to be careful about exposing them publicly. The following is a list of unstable language features that are ok to use within the standard library itself along with any caveats:
 
-- [Const generics](./code-considerations/using-unstable-lang/const-generics.md)
-- [Specialization](./code-considerations/using-unstable-lang/specialization.md)
+- [Const generics](./const-generics.md)
+- [Specialization](./specialization.md)
 - _Something missing?_ Please submit a PR to keep this list up-to-date!
 
 ## For reviewers
diff --git a/src/feature-lifecycle/deprecation.md b/src/feature-lifecycle/deprecation.md
@@ -2,4 +2,6 @@
 
 **Status:** Stub
 
+Public APIs aren't deleted from the standard library. If something shouldn't be used anymore it gets deprecated by adding a `#[rustc_deprecated]` attribute. Deprecating need to go through a Libs FCP, just like stabilizations do.
+
 To try reduce noise in the docs from deprecated items, they should be moved to the bottom of the module or `impl` block so they're rendered at the bottom of the docs page. The docs should then be cut down to focus on why the item is deprecated rather than how you might use it.
diff --git a/src/feature-lifecycle/landing-new-features.md b/src/feature-lifecycle/landing-new-features.md
@@ -3,3 +3,7 @@
 **Status:** Stub
 
 New unstable features can be added and approved without going through a Libs FCP. There should be some buy-in from Libs that a feature is desirable and likely to be stabilized at some point before landing though.
+
+All public items in the standard library need a `#[stable]` or `#[unstable]` attribute on them. When a feature is first added, it gets a `#[unstable]` attribute.
+
+Before a new feature is merged, those `#[unstable]` attributes need to be linked to a [tracking issue](./tracking-issues.md).
diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md
@@ -2,17 +2,16 @@
 
 **Status:** Stub
 
+Feature stabilization involves replacing `#[unstable]` attributes for a feature with `#[stable]` ones.
+
 ## Before writing a PR to stabilize a feature
 
-Check to see if a [FCP] has completed on the [tracking issue]. If not, either ping `@rust-lang/libs` or leave a comment asking about the status of the feature.
+Check to see if a FCP has completed on the [tracking issue](./tracking-issues.md). If not, either ping `@rust-lang/libs` or leave a comment asking about the status of the feature.
 
 ## When there's `const` involved
 
-Const functions can be stabilized in a PR that replaces `#[rustc_const_unstable]` attributes with `#[rustc_const_stable]` ones. The [Constant Evaluation WG] should be pinged for input on whether or not the `const`-ness is something we want to commit to. If it is an intrinsic being exposed that is const-stabilized then `@rust-lang/lang` should also be included in the FCP.
+Const functions can be stabilized in a PR that replaces `#[rustc_const_unstable]` attributes with `#[rustc_const_stable]` ones. The [Constant Evaluation WG](https://github.com/rust-lang/const-eval) should be pinged for input on whether or not the `const`-ness is something we want to commit to. If it is an intrinsic being exposed that is const-stabilized then `@rust-lang/lang` should also be included in the FCP.
 
 Check whether the function internally depends on other unstable `const` functions through `#[allow_internal_unstable]` attributes and consider how the function could be implemented if its internally unstable calls were removed. See the _Stability attributes_ page for more details on `#[allow_internal_unstable]`.
 
 Where `unsafe` and `const` is involved, e.g., for operations which are "unconst", that the const safety argument for the usage also be documented. That is, a `const fn` has additional determinism (e.g. run-time/compile-time results must correspond and the function's output only depends on its inputs...) restrictions that must be preserved, and those should be argued when `unsafe` is used.
-
-[tracking issue]: ./tracking-issues.md
-[FCP]: ./appendix/glossary.md#fcp
diff --git a/src/feature-lifecycle/tracking-issues.md b/src/feature-lifecycle/tracking-issues.md
@@ -3,3 +3,5 @@
 **Status:** Stub
 
 Tracking issues are used to facilitate discussion and report on the status of standard library features. All public APIs need a dedicated tracking issue. Some larger internal units of work may also use them.
+
+There's a template that can be used to fill out the initial tracking issue. The Libs team also maintains [a Cargo tool](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to quickly dump the public API of an unstable feature.
diff --git a/src/tools-and-bots/bors.md b/src/tools-and-bots/bors.md
diff --git a/src/tools-and-bots/crater.md b/src/tools-and-bots/crater.md
diff --git a/src/tools-and-bots/tidy.md b/src/tools-and-bots/tidy.md
diff --git a/src/tools-and-bots/timer.md b/src/tools-and-bots/timer.md
