From 53f084021b2cc33a5a35e6abb435327095dc2073 Mon Sep 17 00:00:00 2001 From: Simon Date: Fri, 12 Feb 2021 19:20:48 +0100 Subject: [PATCH 01/79] CI: Fix typo in cache key --- .github/workflows/ci.yml | 4 ++-- .github/workflows/gh-pages.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index df3d4b9..b517a0b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,7 +25,7 @@ jobs: with: path: | ~/.cargo/bin - key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.DBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} + key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' @@ -63,7 +63,7 @@ jobs: with: path: | ~/.cargo/bin - key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.DBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} + key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index efbde94..7200c48 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -25,7 +25,7 @@ jobs: with: path: | ~/.cargo/bin - key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.DBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} + key: ${{ runner.os }}-${{ steps.mdbook-version.outputs.MDBOOK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }}--${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' From 842a7948e76b304bf3aec98dcf2c0e11250e9439 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Mon, 1 Mar 2021 18:45:59 +0100 Subject: [PATCH 02/79] Updating mdbook and mdbook-linkcheck versions --- .env | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.env b/.env index 56d5244..b194b51 100644 --- a/.env +++ b/.env @@ -1,5 +1,5 @@ -MDBOOK_VERSION=0.4.6 -MDBOOK_LINKCHECK_VERSION=0.7.2 +MDBOOK_VERSION=0.4.7 +MDBOOK_LINKCHECK_VERSION=0.7.4 MDBOOK_TOC_VERSION=0.6.1 GIT_DEPLOY_DIR=book/html From 102d06a7e7f7515ee574830334851a02abf1c893 Mon Sep 17 00:00:00 2001 From: simonsan <14062932+simonsan@users.noreply.github.com> Date: Fri, 14 May 2021 03:23:17 +0200 Subject: [PATCH 03/79] Updating versions --- .env | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.env b/.env index b194b51..aba142f 100644 --- a/.env +++ b/.env @@ -1,6 +1,6 @@ -MDBOOK_VERSION=0.4.7 +MDBOOK_VERSION=0.4.8 MDBOOK_LINKCHECK_VERSION=0.7.4 -MDBOOK_TOC_VERSION=0.6.1 +MDBOOK_TOC_VERSION=0.6.3 GIT_DEPLOY_DIR=book/html GIT_DEPLOY_BRANCH=gh-pages From 01bdfefbf279f88cc53deffee0c966db67050782 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 30 Jun 2021 22:17:09 -0700 Subject: [PATCH 04/79] Add a doc alias policy Based on discussion in 2021-06-30 libs meeting. --- src/SUMMARY.md | 5 ++++ src/documentation/doc-alias-policy.md | 35 +++++++++++++++++++++++++++ src/documentation/summary.md | 1 + 3 files changed, 41 insertions(+) create mode 100644 src/documentation/doc-alias-policy.md create mode 100644 src/documentation/summary.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 68dafbd..6664b2a 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -36,6 +36,11 @@ --- +- [Documentation](./documentation/summary.md) + - [doc alias policy](./documentation/doc-alias-policy.md) + +--- + - [Tools and bots](./tools-and-bots/summary.md) - [`@bors`](./tools-and-bots/bors.md) - [`@rust-timer`](./tools-and-bots/timer.md) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md new file mode 100644 index 0000000..ac56a86 --- /dev/null +++ b/src/documentation/doc-alias-policy.md @@ -0,0 +1,35 @@ +doc alias policy +================ + +Rust's documentation supports adding aliases to any declaration (such as a +function, type, or constant), using the syntax `#[doc(alias = "name")]`. We +want to use doc aliases to help people find what they're looking for, while +keeping those aliases maintainable and high-value. This policy outlines the +cases where we add doc aliases, and the cases where we omit those aliases. + +- We must have a reasonable expectation that people might search for the term + in the documentation search. Rust's documentation provides a name search, not + a full-text search; as such, we expect that people may search for plausible + names, but that for more general documentation searches they'll turn to a web + search engine. + - Related: we don't expect that people are currently searching Rust + documentation for language-specific name from arbitrary languages they're + familiar with, and we don't want to add that as a new documentation search + feature; please don't add aliases based on your favorite language. Those + mappings should live in separate guides or references. We do expect that + people might look for the Rust name of a function they reasonably expect to + exist in Rust (e.g. a system function or a C library function), to try to + figure out what Rust called that function. +- The proposed alias must be a name we would plausibly have used for the + declaration. For instance, `delete` for `remove`, or `popcnt` and `popcount` + for `count_ones`, or `umask` for `mode`, or `mkdir` for `create_dir`. This + feeds into the reasonable expectation that someone might search for the name + and expect to find it ("what did Rust call `mkdir`"). +- There must be an obvious single target for the alias that is an *exact* + analogue of the aliased name. We will not add the same alias to multiple + declarations. We will also not add an alias for a function that's only + somewhat similar or related. +- The alias must not conflict with the actual name of any existing declaration. +- As a special case for stdarch, aliases from exact assembly instruction names + to the corresponding intrinsic function are welcome, as long as they don't + conflict with other names. diff --git a/src/documentation/summary.md b/src/documentation/summary.md new file mode 100644 index 0000000..1fb6e93 --- /dev/null +++ b/src/documentation/summary.md @@ -0,0 +1 @@ +- [doc alias policy](./doc-alias-policy.md) From 8715f19f57fc1739f6d1ee74b39d8d2683e26ea4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Fri, 2 Jul 2021 00:31:39 -0700 Subject: [PATCH 05/79] Note that `const` and non-`const` versions of the same function are fine --- src/documentation/doc-alias-policy.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index ac56a86..fa730d2 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -27,8 +27,9 @@ cases where we add doc aliases, and the cases where we omit those aliases. and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple - declarations. We will also not add an alias for a function that's only - somewhat similar or related. + declarations. (`const` and non-`const` versions of the same function are + fine.) We will also not add an alias for a function that's only somewhat + similar or related. - The alias must not conflict with the actual name of any existing declaration. - As a special case for stdarch, aliases from exact assembly instruction names to the corresponding intrinsic function are welcome, as long as they don't From 27898ab76c707439047b7a35fbac3d860ccd61a2 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:18:55 -0700 Subject: [PATCH 06/79] Drop `delete` example; give example of `rmdir` instead --- src/documentation/doc-alias-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index fa730d2..7830792 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -21,10 +21,10 @@ cases where we add doc aliases, and the cases where we omit those aliases. exist in Rust (e.g. a system function or a C library function), to try to figure out what Rust called that function. - The proposed alias must be a name we would plausibly have used for the - declaration. For instance, `delete` for `remove`, or `popcnt` and `popcount` - for `count_ones`, or `umask` for `mode`, or `mkdir` for `create_dir`. This - feeds into the reasonable expectation that someone might search for the name - and expect to find it ("what did Rust call `mkdir`"). + declaration. For instance, `rmdir` for `remove_dir`, or `popcnt` and + `popcount` for `count_ones`, or `umask` for `mode`, or `mkdir` for + `create_dir`. This feeds into the reasonable expectation that someone might + search for the name and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple declarations. (`const` and non-`const` versions of the same function are From 339b3fe0dcf828cdccd29fc9fb6f2efa28aa117f Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:21:56 -0700 Subject: [PATCH 07/79] Reorder examples --- src/documentation/doc-alias-policy.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index 7830792..0d3dd05 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -21,10 +21,10 @@ cases where we add doc aliases, and the cases where we omit those aliases. exist in Rust (e.g. a system function or a C library function), to try to figure out what Rust called that function. - The proposed alias must be a name we would plausibly have used for the - declaration. For instance, `rmdir` for `remove_dir`, or `popcnt` and - `popcount` for `count_ones`, or `umask` for `mode`, or `mkdir` for - `create_dir`. This feeds into the reasonable expectation that someone might - search for the name and expect to find it ("what did Rust call `mkdir`"). + declaration. For instance, `mkdir` for `create_dir`, or `rmdir` for + `remove_dir`, or `popcnt` and `popcount` for `count_ones`, or `umask` for + `mode`. This feeds into the reasonable expectation that someone might search + for the name and expect to find it ("what did Rust call `mkdir`"). - There must be an obvious single target for the alias that is an *exact* analogue of the aliased name. We will not add the same alias to multiple declarations. (`const` and non-`const` versions of the same function are From 29d77cd7d8c8bd2c4c7167febd2b5a2f75309fd4 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 7 Jul 2021 11:22:33 -0700 Subject: [PATCH 08/79] Fix typo Co-authored-by: Jane Lusby --- src/documentation/doc-alias-policy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/documentation/doc-alias-policy.md b/src/documentation/doc-alias-policy.md index 0d3dd05..fedfad1 100644 --- a/src/documentation/doc-alias-policy.md +++ b/src/documentation/doc-alias-policy.md @@ -13,7 +13,7 @@ cases where we add doc aliases, and the cases where we omit those aliases. names, but that for more general documentation searches they'll turn to a web search engine. - Related: we don't expect that people are currently searching Rust - documentation for language-specific name from arbitrary languages they're + documentation for language-specific names from arbitrary languages they're familiar with, and we don't want to add that as a new documentation search feature; please don't add aliases based on your favorite language. Those mappings should live in separate guides or references. We do expect that From 8fb36bd37cb8860785e0a743276c49789da38027 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Wed, 14 Jul 2021 16:33:48 +0200 Subject: [PATCH 09/79] Add SAFETY comments presentation --- src/documentation/safety-comments.md | 79 ++++++++++++++++++++++++++++ src/documentation/summary.md | 1 + 2 files changed, 80 insertions(+) create mode 100644 src/documentation/safety-comments.md diff --git a/src/documentation/safety-comments.md b/src/documentation/safety-comments.md new file mode 100644 index 0000000..c13ae96 --- /dev/null +++ b/src/documentation/safety-comments.md @@ -0,0 +1,79 @@ +# Safety comments + +Using [`unsafe`] blocks in often required in the Rust compiler or standard +library, but this is not done without rules: each `unsafe` block should have +a `SAFETY:` comment explaining why the block is safe, which invariants are +used and must be respected. Below are some examples taken from the standard +library: + +[`unsafe`]: https://doc.rust-lang.org/stable/std/keyword.unsafe.html + +## Inside `unsafe` elements + +This one shows how an `unsafe` function can pass the requirements through to its +caller with the use of documentation in a `# Safety` section while still having +more invariants needed that are not required from callers. `clippy` has a +lint for `# Safety` sections by the way. + +```rust +/// Converts a mutable string slice to a mutable byte slice. +/// +/// # Safety +/// +/// The caller must ensure that the content of the slice is valid UTF-8 +/// before the borrow ends and the underlying `str` is used. +/// +/// Use of a `str` whose contents are not valid UTF-8 is undefined behavior. +/// +/// ... +pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] { + // SAFETY: the cast from `&str` to `&[u8]` is safe since `str` + // has the same layout as `&[u8]` (only libstd can make this guarantee). + // The pointer dereference is safe since it comes from a mutable reference which + // is guaranteed to be valid for writes. + unsafe { &mut *(self as *mut str as *mut [u8]) } +} +``` + +[See the function on github][as_bytes_mut] + +This example is for a function but the same principle applies to `unsafe trait`s +like [`Send`] or [`Sync`] for example, though they have no `# Safety` section +since their entire documentation is about why they are `unsafe`. + +Note that in the Rust standard library, [`unsafe_op_in_unsafe_fn`] is active +and so each `unsafe` operation in an `unsafe` function must be enclosed in an +`unsafe` block. This makes it easier to review such functions and to document +their `unsafe` parts. + +[`Send`]: https://doc.rust-lang.org/stable/std/marker/trait.Send.html +[`Sync`]: https://doc.rust-lang.org/stable/std/marker/trait.Sync.html +[as_bytes_mut]: https://github.com/rust-lang/rust/blob/a08f25a7ef2800af5525762e981c24d96c14febe/library/core/src/str/mod.rs#L278 +[`unsafe_op_in_unsafe_fn`]: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unsafe-op-in-unsafe-fn + +## Inside *safe* elements + +Inside safe elements, a `SAFETY:` comment must not depend on anything from the +caller beside properly contruscted types and values (i.e, if your function +receive a reference that is unaligned or null, it's the caller fault if it fails +and not yours). + +`SAFETY` comments in *safe* elements often rely on checks that are done before +the `unsafe` block or on type invariants, like a division by `NonZeroU8` would +not check for `0` before dividing. + +```rust +pub fn split_at(&self, mid: usize) -> (&str, &str) { + // is_char_boundary checks that the index is in [0, .len()] + if self.is_char_boundary(mid) { + // SAFETY: just checked that `mid` is on a char boundary. + unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) } + } else { + slice_error_fail(self, 0, mid) + } +} +``` + +[See the function on github][split_at] + +[split_at]: https://github.com/rust-lang/rust/blob/a08f25a7ef2800af5525762e981c24d96c14febe/library/core/src/str/mod.rs#L570 diff --git a/src/documentation/summary.md b/src/documentation/summary.md index 1fb6e93..686bcac 100644 --- a/src/documentation/summary.md +++ b/src/documentation/summary.md @@ -1 +1,2 @@ - [doc alias policy](./doc-alias-policy.md) +- [safety comments policy](./safety-comments.md) From d91d00502f877ed94f5958832ab93b06bbc3169a Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Sat, 17 Jul 2021 14:38:27 +0200 Subject: [PATCH 10/79] Fix typos, move example link above the example --- src/documentation/safety-comments.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/documentation/safety-comments.md b/src/documentation/safety-comments.md index c13ae96..5cbe19d 100644 --- a/src/documentation/safety-comments.md +++ b/src/documentation/safety-comments.md @@ -1,6 +1,6 @@ # Safety comments -Using [`unsafe`] blocks in often required in the Rust compiler or standard +Using [`unsafe`] blocks is often required in the Rust compiler or standard library, but this is not done without rules: each `unsafe` block should have a `SAFETY:` comment explaining why the block is safe, which invariants are used and must be respected. Below are some examples taken from the standard @@ -15,6 +15,8 @@ caller with the use of documentation in a `# Safety` section while still having more invariants needed that are not required from callers. `clippy` has a lint for `# Safety` sections by the way. +[See the example on github][as_bytes_mut] + ```rust /// Converts a mutable string slice to a mutable byte slice. /// @@ -35,8 +37,6 @@ pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] { } ``` -[See the function on github][as_bytes_mut] - This example is for a function but the same principle applies to `unsafe trait`s like [`Send`] or [`Sync`] for example, though they have no `# Safety` section since their entire documentation is about why they are `unsafe`. @@ -54,14 +54,16 @@ their `unsafe` parts. ## Inside *safe* elements Inside safe elements, a `SAFETY:` comment must not depend on anything from the -caller beside properly contruscted types and values (i.e, if your function -receive a reference that is unaligned or null, it's the caller fault if it fails -and not yours). +caller beside properly constructed types and values (i.e, if your function +receives a reference that is unaligned or null, it is the caller fault if it +fails and not yours). `SAFETY` comments in *safe* elements often rely on checks that are done before the `unsafe` block or on type invariants, like a division by `NonZeroU8` would not check for `0` before dividing. +[See the example on github][split_at] + ```rust pub fn split_at(&self, mid: usize) -> (&str, &str) { // is_char_boundary checks that the index is in [0, .len()] @@ -74,6 +76,4 @@ pub fn split_at(&self, mid: usize) -> (&str, &str) { } ``` -[See the function on github][split_at] - [split_at]: https://github.com/rust-lang/rust/blob/a08f25a7ef2800af5525762e981c24d96c14febe/library/core/src/str/mod.rs#L570 From 5380af33e9b1a86575fa5da90dc9ea2e509f64f6 Mon Sep 17 00:00:00 2001 From: Amanieu d'Antras Date: Sun, 18 Jul 2021 23:20:11 +0100 Subject: [PATCH 11/79] Notes on making breaking changes to the prelude --- .../breaking-changes/prelude.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 src/code-considerations/breaking-changes/prelude.md diff --git a/src/code-considerations/breaking-changes/prelude.md b/src/code-considerations/breaking-changes/prelude.md new file mode 100644 index 0000000..6c4a4d0 --- /dev/null +++ b/src/code-considerations/breaking-changes/prelude.md @@ -0,0 +1,15 @@ +# 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. + +## 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. + +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. + +This issues was encoutered when trying to land the [`assert_matches!` macro](https://github.com/rust-lang/rust/issues/82913). From af87c09f689686ddd44d2bddd7e3a426e666eedb Mon Sep 17 00:00:00 2001 From: Amanieu d'Antras Date: Wed, 21 Jul 2021 21:06:05 +0100 Subject: [PATCH 12/79] Update SUMMARY.md --- src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6664b2a..887d410 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -24,6 +24,7 @@ - [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) From 7c499e2a4ceffedac6972614294bec1ec09bc361 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 22 Sep 2021 18:23:35 +0200 Subject: [PATCH 13/79] Add documentation about the libs teams and membership. --- book.toml | 6 ++-- src/SUMMARY.md | 5 +++- src/meetings.md | 21 +++++++++++++ src/membership.md | 35 ++++++++++++++++++++++ src/reviewer-checklist.md | 51 ------------------------------- src/reviewing.md | 36 ++++++++++++++++++++++ src/team.md | 63 +++++++++++++++++++++++++++++++++++++++ 7 files changed, 162 insertions(+), 55 deletions(-) create mode 100644 src/meetings.md create mode 100644 src/membership.md delete mode 100644 src/reviewer-checklist.md create mode 100644 src/reviewing.md create mode 100644 src/team.md diff --git a/book.toml b/book.toml index d7a254f..4699954 100644 --- a/book.toml +++ b/book.toml @@ -7,7 +7,7 @@ multilingual = false src = "./src" [build] -create-missing = false +create-missing = true [rust] edition = "2018" @@ -19,6 +19,6 @@ renderer = ["html"] [output.linkcheck] [output.html] -default-theme = "rust" -git-repository-url = "https://github.com/rust-lang/std-dev-guide" 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}" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 887d410..c48ccf8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,7 +4,10 @@ [Getting started](./getting-started.md) -[Reviewer checklist](./reviewer-checklist.md) +- [The library team](./team.md) + - [Meetings](./meetings.md) + - [Membership](./membership.md) + - [Reviewing](./reviewing.md) --- diff --git a/src/meetings.md b/src/meetings.md new file mode 100644 index 0000000..4156539 --- /dev/null +++ b/src/meetings.md @@ -0,0 +1,21 @@ +# Meetings + +Currently, both the Library Team and the Library API Team have a weekly hour-long meeting. +Both meetings are open to non-members by default, although some might be (partially) private when agenda topics require that. + +The meetings are held as video calls through [Jitsi](https://meet.jit.si/), but everyone is welcome to join without video or even audio. +If you want to participate in meeting discussions through text, you can do so through Jitsi's chat function. + +Meetings and their agendas are announced in the [#t-libs/meetings](https://rust-lang.zulipchat.com/#narrow/stream/259402-t-libs.2Fmeetings) channel on Zulip. + +Agendas are generated by the [`fully-automatic-rust-libs-team-triage-meeting-agenda-generator`](https://github.com/rust-lang/libs-team/tree/main/tools/agenda-generator), +which will include all relevant issues and PRs, such as those tagged with `I-nominated` or `S-waiting-on-team`. + +If you have any specific topics you'd like to have discussed in a meeting, feel free to open an issue on the [`libs-team`](https://github.com/rust-lang/libs-team/) repository +and mark it as `I-nominated` and `T-libs` or `T-libs-api`. Or just leave a message in the Zulip channel. + +All the meetings, including those of the library working groups, can be found on our Google Calendar: + + + +[ICS link](https://calendar.google.com/calendar/ical/9kuu8evq4eh6uacm262k0phri8%40group.calendar.google.com/public/basic.ics) diff --git a/src/membership.md b/src/membership.md new file mode 100644 index 0000000..f7d9c16 --- /dev/null +++ b/src/membership.md @@ -0,0 +1,35 @@ +# Membership + +## Library Contributors + +Membership to Library Contributors can be offered by the Library Team once +a regular contributor has made a number of significant contributions over some period of time, +and has shown to have a good judgement on what changes are acceptable. + +## The Library Team and Library API Team + +The Library Team and Library API Team pick their own members, +although it's expected that new members come from the Library Contributors or another Rust team, +and have already been involved in relevant library work. + +## The process + +In all cases, the process of adding a new members goes as follows: + +1. A member of the Library (API) Team proposes the addition of a contributor on our private mailing list. + This includes proposal includes: + - A short description of what this person has been working on; how they have been contributing. + - A few specific examples of cases where this person clearly communicated their ideas. + - A few specific examples that show this person understands what are and what aren't acceptable changes.\ + Someone who makes significant contributions but usually needs to make large adjustments to their PRs might be a wonderful external contributor, + but might not yet be a good match for membership with review persmissions expecting to judge other contributions. +2. Every single team member is asked for their input. No team member must have any objections. + - Objections are ideally shared with the entire team, but may also be shared privately with the team lead or the moderation team. + - Objections ideally include examples showing behavior not in line with the expectations described under step 1 + (or the code of conduct). +3. The team lead reaches out to the moderation team to ask if they are aware of any objections. +4. Only once the team members and the moderation team agree, the new contributor is invited to join. +5. If the new contributor agrees too, a PR is sent to the `team` repository to add them. +6. A blog post is published in the Internals Blog with a short introduction of the new contributor. + The contents of this post can be based on some of the points brought up in the email from step 1. + The contents are first checked with the new contributor before it is published. diff --git a/src/reviewer-checklist.md b/src/reviewer-checklist.md deleted file mode 100644 index a9192c9..0000000 --- a/src/reviewer-checklist.md +++ /dev/null @@ -1,51 +0,0 @@ -# Reviewer checklist - -**Status:** Stub - -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: - -```ignore -r? @user -``` - -## Before you review - -- [ ] Is this a [stabilization](./feature-lifecycle/stabilization.md) or [deprecation](./feature-lifecycle/deprecation.md)? - - [ ] Make sure there's a completed FCP somewhere for it. - - [ ] Ping `@rust-lang/libs` for input. - -## As you review - -Look out for code considerations: - -- [ ] [Design](./code-considerations/design/summary.md) -- [ ] [Breaking changes](./code-considerations/breaking-changes/summary.md) -- [ ] [Safety and soundness](./code-considerations/safety-and-soundness/summary.md) -- [ ] [Use of unstable language features](./code-considerations/using-unstable-lang/summary.md) -- [ ] [Performance](./code-considerations/performance/summary.md) - -## Before you merge - -- [ ] Is the commit log tidy? Avoid merge commits, these can be squashed down. -- [ ] Can this change be rolled up? -- [ ] Is this a [new unstable feature](./feature-lifecycle/new-unstable-features.md)? - - [ ] Create a [tracking issue](./feature-lifecycle/tracking-issues.md). - - [ ] Update the `#[unstable]` attributes to point to it. - -## When you're ready - -Use [`@bors`](./tools-and-bots/bors.md) to merge the pull request. - -To roll up: - -```ignore -@bors r+ rollup -``` - -or just: - -```ignore -@bors r+ -``` diff --git a/src/reviewing.md b/src/reviewing.md new file mode 100644 index 0000000..169a547 --- /dev/null +++ b/src/reviewing.md @@ -0,0 +1,36 @@ +# Reviewing + +Every member of the Library Team, Library API Team, and Library Contributors has 'r+ rights'. +That is, the ability to approve a PR and instruct [`@bors`](https://bors.rust-lang.org/) +to test and merge it into Rust nightly. + +If you decide to review a PR, thank you! +But please keep in mind: + +- You are always welcome to review any PR, regardless of who it is assigned to. + However, do not approve PRs unless: + - You are confident that nobody else wants to review it first. If you think someone else on the team would be a better person to review it, feel free to reassign it to them. + - You are confident in that part of the code. + - You are confident it will not cause any breakage or regress performance. + - It does not change the public API, including any stable promises we make in documentation, unless there's a finished FCP for the change. + - For unstable API changes/additions, it can be acceptable to skip the RFC process if the design is small and the change is uncontroversial. + Make sure to involve `@rust-lang/libs-api` on such changes. +- Always be polite when reviewing: you are a representative of the Rust project, so it is expected that you will go above and beyond when it comes to the Code of Conduct. + +## High-five rotation + +Some of the members of the team are part of the 'high-five rotation'; +the list from which the high-five bot picks reviewers to assign new PRs to. + +Being a member of one of the teams does not come with the expectation to be on this list. +However, members of this list should be on at least one of the three library teams. + +If the bot assigns you a PR for which you do not have the time or expertise to review it, +feel free to reassign it to someone else. +To assign it to another random person picked from the high-five rotation, +use `r? libs`. + +If you find yourself unable to keep up with reviews, +it might be a good idea to (temporarily) remove yourself from the list. +To add or remove yourself from the list, send a PR to change the +[high-five configuration file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json). diff --git a/src/team.md b/src/team.md new file mode 100644 index 0000000..4b71424 --- /dev/null +++ b/src/team.md @@ -0,0 +1,63 @@ +# The Library Team + +The Rust standard library and the official `rust-lang` crates are +the responsibility of the Library Team. +The Library team makes sure the libraries are maintained, +PRs get reviewed, and issues get handled in time, +although that does not mean the team members are doing all the work themselves. +Many team members and other contributors are involved in this work, +and the team's main task is to guide and enable that work. + +## The Library API Team + +A very critical aspect of maintaining and evolving the standard library is its stability. +Unlike other crates, we can not release a new major version once in a while for backwards +incompatible changes. Every version of the standard library is semver-compatible +with all previous versions since Rust 1.0. + +This means that we have to be very careful with additions and changes to the public interface. +We can deprecate things if necessary, +but removing items or changing signatures is almost never an option. +As a result, we are very careful with stabilizing additions to the standard library. +Once something is stable, we're basically stuck with it forever. + +To guard the stability and prevent us from adding things we'll regret later, +we have a team that specifically focusses on the public API. +Every RFC and stabilization of a library addition/change goes through a FCP process +in which the members of the Library API Team are asked to sign off on the change. + +The members of this team are not necessarily familiar with the implementation details +of the standard library, but are experienced with API design and understand the details +of breaking changes and how they are avoided. + +## The Library Contributors + +In addition to the two teams above, we also have a the Library Contributors, +which is a somewhat more loosely defined team consisting of those who regularly contribute +or review changes to the standard libraries. + +Many of these contributors have a specific area of expertise, +for example certain data structures or a specific operating system. + +## Team Membership + +The Library Team will privately discuss potential new members for itself and Library Contributors, +and extend an invitation after all members and the moderation team is on board with the potential addition. + +See [Membership](./membership.md) for details. + +### r+ permission + +All members of the Library Team, the Library API Team, and the Library Contributors +can approve any PR, as long as they are confident in their review +and are sure no one else needs to be involved in the review. +See [Reviewing](./reviewing.md) for details. + +### high-five rotation + +Some of the members of the team are part of the 'high-five rotation'; +the list from which the high-five bot picks reviewers to assign new PRs to. + +Being a member of one of the teams does not come with the expectation to be on this list. +However, members of this list should be on at least one of the three library teams. +See [Reviewing](./reviewing.md) for details. From a2f4d46e3b7d6426a43a94341788037cbb87f2d9 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:17:50 +0200 Subject: [PATCH 14/79] Update src/reviewing.md Co-authored-by: Jane Lusby --- src/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reviewing.md b/src/reviewing.md index 169a547..a6a6e46 100644 --- a/src/reviewing.md +++ b/src/reviewing.md @@ -28,7 +28,7 @@ However, members of this list should be on at least one of the three library tea If the bot assigns you a PR for which you do not have the time or expertise to review it, feel free to reassign it to someone else. To assign it to another random person picked from the high-five rotation, -use `r? libs`. +use `r? rust-lang/libs`. If you find yourself unable to keep up with reviews, it might be a good idea to (temporarily) remove yourself from the list. From 9a85a567c51650858884fc744344162b98318728 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:17:55 +0200 Subject: [PATCH 15/79] Update src/team.md Co-authored-by: Jane Lusby --- src/team.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/team.md b/src/team.md index 4b71424..27f88be 100644 --- a/src/team.md +++ b/src/team.md @@ -22,7 +22,7 @@ As a result, we are very careful with stabilizing additions to the standard libr Once something is stable, we're basically stuck with it forever. To guard the stability and prevent us from adding things we'll regret later, -we have a team that specifically focusses on the public API. +we have a team that specifically focuses on the public API. Every RFC and stabilization of a library addition/change goes through a FCP process in which the members of the Library API Team are asked to sign off on the change. From ecacfde88735df9e092da9440047c10b4e12a49d Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 25 Sep 2021 22:18:05 +0200 Subject: [PATCH 16/79] Update src/membership.md Co-authored-by: Jane Lusby --- src/membership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/membership.md b/src/membership.md index f7d9c16..bfde003 100644 --- a/src/membership.md +++ b/src/membership.md @@ -17,7 +17,7 @@ and have already been involved in relevant library work. In all cases, the process of adding a new members goes as follows: 1. A member of the Library (API) Team proposes the addition of a contributor on our private mailing list. - This includes proposal includes: + This proposal includes: - A short description of what this person has been working on; how they have been contributing. - A few specific examples of cases where this person clearly communicated their ideas. - A few specific examples that show this person understands what are and what aren't acceptable changes.\ From 929ec76ca413b2f48c53a19ed1eeaf763ce5e3dd Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 29 Sep 2021 12:58:35 +0200 Subject: [PATCH 17/79] Typo. Co-authored-by: Josh Stone --- src/membership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/membership.md b/src/membership.md index bfde003..0c22dea 100644 --- a/src/membership.md +++ b/src/membership.md @@ -22,7 +22,7 @@ In all cases, the process of adding a new members goes as follows: - A few specific examples of cases where this person clearly communicated their ideas. - A few specific examples that show this person understands what are and what aren't acceptable changes.\ Someone who makes significant contributions but usually needs to make large adjustments to their PRs might be a wonderful external contributor, - but might not yet be a good match for membership with review persmissions expecting to judge other contributions. + but might not yet be a good match for membership with review permissions expecting to judge other contributions. 2. Every single team member is asked for their input. No team member must have any objections. - Objections are ideally shared with the entire team, but may also be shared privately with the team lead or the moderation team. - Objections ideally include examples showing behavior not in line with the expectations described under step 1 From 2187a1f263236982566524dc2d5bdec0dca5dd49 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Wed, 29 Sep 2021 12:58:13 +0200 Subject: [PATCH 18/79] Update wording. --- src/team.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/team.md b/src/team.md index 27f88be..5e01dac 100644 --- a/src/team.md +++ b/src/team.md @@ -49,8 +49,7 @@ See [Membership](./membership.md) for details. ### r+ permission All members of the Library Team, the Library API Team, and the Library Contributors -can approve any PR, as long as they are confident in their review -and are sure no one else needs to be involved in the review. +have the permission to approve PRs, and are expected handle this with care. See [Reviewing](./reviewing.md) for details. ### high-five rotation From 83c8e284b63ceceb4e427f32829bef2cddf90287 Mon Sep 17 00:00:00 2001 From: Matthew Jasper Date: Mon, 4 Oct 2021 21:19:25 +0100 Subject: [PATCH 19/79] Document internal specialization attributes --- .../using-unstable-lang/specialization.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/src/code-considerations/using-unstable-lang/specialization.md b/src/code-considerations/using-unstable-lang/specialization.md index a390b15..6385b9a 100644 --- a/src/code-considerations/using-unstable-lang/specialization.md +++ b/src/code-considerations/using-unstable-lang/specialization.md @@ -58,6 +58,39 @@ impl RcFromSlice for Rc<[T]> { Only specialization using the `min_specialization` feature should be used. The full `specialization` feature is known to be unsound. +## Specialization attributes + +There are two unstable attributes that can be used to allow a trait bound in a specializing implementation that does not appear in the default implementation. + +`rustc_specialization_trait` restricts the implementations of a trait to be "always applicable". Implementing traits annotated with `rustc_specialization_trait` is unstable, so this should not be used on any stable traits exported from the standard library. `Sized` is an exception, and can have this attribute because it already cannot be implemented by an `impl` block. + +`rustc_unsafe_specialization_marker` allows specializing on a trait with no associated items. The attribute is `unsafe` because lifetime constraints from the implementations of the trait are not considered when specializing. In the following example, the specialized implementation is used for *all* shared reference types, not just those with `'static` lifetime. + +```rust,ignore +#[rustc_unsafe_specialization_marker] +trait StaticRef {} + +impl StaticRef for &'static T {} + +trait DoThing: Sized { + fn do_thing(self); +} + +impl DoThing for T { + default fn do_thing(self) { + // slow impl + } +} + +impl DoThing for T { + fn do_thing(self) { + // fast impl + } +} +``` + +`rustc_unsafe_specialization_marker` exists to allow existing specializations that are based on marker traits exported from `std`, such as `Copy`, `FusedIterator` or `Eq`. New uses of `rustc_unsafe_specialization_marker` should be avoided. + ## For reviewers Look out for any `default` annotations on public trait implementations. These will need to be refactored into a private dispatch trait. Also look out for uses of specialization that do more than pick a more optimized implementation. From 5ae297ef3a30e8f92c630b7589f5cd10781b3636 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Tue, 26 Oct 2021 13:00:22 +0200 Subject: [PATCH 20/79] Update high-five rotation guideline. --- src/reviewing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/reviewing.md b/src/reviewing.md index a6a6e46..a6535f8 100644 --- a/src/reviewing.md +++ b/src/reviewing.md @@ -30,7 +30,7 @@ feel free to reassign it to someone else. To assign it to another random person picked from the high-five rotation, use `r? rust-lang/libs`. -If you find yourself unable to keep up with reviews, +If you find yourself unable to do any reviews for an extended period of time, it might be a good idea to (temporarily) remove yourself from the list. To add or remove yourself from the list, send a PR to change the [high-five configuration file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json). From fb852e98770f1b3c71c8bfd78f32c1bf9f9051f7 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 3 Mar 2022 14:54:10 -0800 Subject: [PATCH 21/79] Update stabilization documentation --- src/feature-lifecycle/stabilization.md | 27 +++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index f361efd..49b08e5 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,6 +1,7 @@ # Stabilizing features -**Status:** Stub +**Status:** Current +**Last Updated:** 2022/03/03 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -12,11 +13,11 @@ Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs` This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course. -## Writing a stabilization PR +## Partial Stabilizations + +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. -- Replace any `#[unstable]` attributes for the given feature with stable ones. The value of the `since` field is usually the current `nightly` version. -- Remove any `#![feature()]` attributes that were previously required. -- Submit a PR with a stabilization report. +You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). ## When there's `const` involved @@ -25,3 +26,19 @@ Const functions can be stabilized in a PR that replaces `#[rustc_const_unstable] 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. + +## Writing a stabilization PR + +To stabilize a feature, follow these steps: + +0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable as preferred. If you're unsure which way is best ask a libs-api team member. +0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). +0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. +0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. +0. Open a PR against `rust-lang/rust`. + - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. + - Link to the tracking issue and say "Closes #XXXXX". + +You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). + From 4e2218857a21f1c78bb956180aa957445b5d3e47 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 3 Mar 2022 15:46:16 -0800 Subject: [PATCH 22/79] add detailed section that scottmcm wrote for rustc dev guide --- src/feature-lifecycle/stabilization.md | 57 ++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 49b08e5..fcdec9f 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -15,7 +15,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. How you split up that feature is situational and depends on the specific feature and how you're splitting it up, so in some cases you may want to create a new tracking issue for the portion being stabilized, and in other situations you may want to use the new tracking issue to track the portion being left unstable. If you're unsure how to split up the issue you can always ask a libs-api team member for guidance in the original tracking issue or in the [libs team zulip](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs). You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). @@ -27,11 +27,62 @@ Check whether the function internally depends on other unstable `const` function 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. -## Writing a stabilization PR +## Stabilization PR for Library Features + +Once we have decided to stabilize a feature, we need to have a PR that actually makes that stabilization happen. These kinds of PRs are a great way to get involved in Rust, as they're typically small -- just updating attributes. + +Here is a general guide to how to stabilize a feature -- every feature is different, of course, so some features may require steps beyond what this guide talks about. + +### Update the stability attributes on the items + +Library items are marked unstable via the `#[unstable]` attribute, like this: + +```rust,ignore +#[unstable(feature = "total_cmp", issue = "72599")] +pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { ... } +``` + +You'll need to change that to a `#[stable]` attribute with a version: + +```rust,ignore +#[stable(feature = "total_cmp", since = "1.61.0")] +``` + +Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [the forge](https://forge.rust-lang.org/#current-release-versions). Specifically, you'll want to use the version labelled "Nightly". That's two versions higher than the current stable release, as what's currently in beta will be the next stable release, and any change you're making now will be in the one after that. + +### Remove feature gates from doctests + +All the doctests on the items being stabilized will be enabling the unstable feature, so now that it's stable those attributes are no longer needed and should be removed. + +`````diff + /// # Examples + /// + /// ``` +-/// #![feature(total_cmp)] +-/// + /// assert_eq!(0.0_f32.total_cmp(&-0.0), std::cmp::Ordering::Greater); + /// ``` +````` + +The most obvious place to find these is on the item itself, but it's worth searching the whole library. Often you'll find other unstable methods that were also using it in their tests. + +### Remove feature gates from the compiler + +The compiler builds with nightly features allowed, so you may find uses of the feature there as well. These also need to be removed. + +```diff + #![feature(once_cell)] + #![feature(never_type)] +-#![feature(total_cmp)] + #![feature(trusted_step)] + #![feature(try_blocks)] +``` + +## Stabilization PR Checklist To stabilize a feature, follow these steps: -0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable as preferred. If you're unsure which way is best ask a libs-api team member. +0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable, whichever makes the most sense based on the situation. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From 53428b028d28e8e0318f3ee6ab4a582108005ab8 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:30:52 -0800 Subject: [PATCH 23/79] add section on stabilization reports --- src/feature-lifecycle/stabilization.md | 27 ++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index fcdec9f..fa2b3c7 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,11 +1,33 @@ # Stabilizing features **Status:** Current -**Last Updated:** 2022/03/03 +**Last Updated:** 2022/03/10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. + +## When is an FCP appropriate? + +Once an unstable feature has been well-tested with no outstanding concerns, +anyone may push for it's stabilization. If you're unsure if a feature is ready +for stabilization the first step should be to ask in the relevant tracking +issue and get assistance from other participants in that discussion. In some +cases the tracking issue may not have many other active participants, so if +you're ever having trouble getting any feedback please ping one of the [libs +team +reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) +directly to request assistance. + +## Stabilization Report + +Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. + +The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. + +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. + +The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. ## Before writing a PR to stabilize a feature @@ -93,3 +115,4 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). +[^1]: FCP stands for final comment period From fda8cacf6bbcd82f56420fda92bb8372d110aa6f Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:44:08 -0800 Subject: [PATCH 24/79] fix formatting --- src/feature-lifecycle/stabilization.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index fa2b3c7..344208b 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,15 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, -anyone may push for it's stabilization. If you're unsure if a feature is ready -for stabilization the first step should be to ask in the relevant tracking -issue and get assistance from other participants in that discussion. In some -cases the tracking issue may not have many other active participants, so if -you're ever having trouble getting any feedback please ping one of the [libs -team -reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) -directly to request assistance. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## Stabilization Report From 9a1909cbfab4d1743f1cc5a708562f99d946bada Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Thu, 10 Mar 2022 16:47:47 -0800 Subject: [PATCH 25/79] specify exactly how to handle a partial stabilization --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 344208b..549eb7a 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -29,7 +29,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. How you split up that feature is situational and depends on the specific feature and how you're splitting it up, so in some cases you may want to create a new tracking issue for the portion being stabilized, and in other situations you may want to use the new tracking issue to track the portion being left unstable. If you're unsure how to split up the issue you can always ask a libs-api team member for guidance in the original tracking issue or in the [libs team zulip](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs). +When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). From 927f807e36da12506fa236745669ead537bff369 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 11 Mar 2022 11:48:09 -0800 Subject: [PATCH 26/79] fix inconsistencies with docs for partial stabilization --- src/feature-lifecycle/stabilization.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 549eb7a..6dd7bba 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,7 +9,9 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. + +If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## Stabilization Report @@ -31,7 +33,9 @@ This will save you from opening a stabilization PR and having it need regular re When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. -You can see an example of partially stabilizing a feature with tracking issues [#71146](https://github.com/rust-lang/rust/issues/71146) and [XXXXX]() with FCP and the associated implementation PR [XXXXX](). +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). + +If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. ## When there's `const` involved @@ -96,7 +100,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: -0. (Optional) For partial stabilizations, create a new tracking issue for either the subset being stabilized or the subset being left unstable, whichever makes the most sense based on the situation. +0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. @@ -108,3 +112,4 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). [^1]: FCP stands for final comment period + From af2581b7de8342e2ac15f1514c532597580a3d50 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 11 Mar 2022 11:59:05 -0800 Subject: [PATCH 27/79] more clarifications --- src/feature-lifecycle/stabilization.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 6dd7bba..857465a 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,7 +1,7 @@ # Stabilizing features -**Status:** Current -**Last Updated:** 2022/03/10 +* **Status:** Current +* **Last Updated:** 2022/03/10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -23,6 +23,8 @@ The **API Summary** section should include a precise description of what APIs ar The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. +You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). + ## Before writing a PR to stabilize a feature Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs` or leave a comment asking about the status of the feature. @@ -31,12 +33,12 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature your first step should be to split the feature into multiple features, each with their own tracking issues. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. - -You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization + tracking PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). + ## 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](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. @@ -100,6 +102,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: +0. Create a stabiliation report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). From 1e6c361dd25614f62421e868c430f446e1287c14 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:39:24 -0700 Subject: [PATCH 28/79] Apply suggestions from code review Co-authored-by: Mara Bos --- src/feature-lifecycle/stabilization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 857465a..dd318e1 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,7 +1,7 @@ # Stabilizing features * **Status:** Current -* **Last Updated:** 2022/03/10 +* **Last Updated:** 2022-03-10 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. @@ -9,7 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for it's stabilization. +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. @@ -110,7 +110,7 @@ To stabilize a feature, follow these steps: 0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. 0. Open a PR against `rust-lang/rust`. - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. - - Link to the tracking issue and say "Closes #XXXXX". + - Link to the tracking issue by adding "Closes #XXXXX". You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). From 4fc10426ef3525deff88251d70b48138ce8c6e07 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:45:04 -0700 Subject: [PATCH 29/79] note that api summary can link back to top level tracking issue comment if up to date --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index dd318e1..2b3f9f6 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -19,7 +19,7 @@ Once a feature is ready for stabilization the first step of the FCP process is w The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. -The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. From 60625ff37f4e0c1fb741704fcfd7909440e49341 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:46:07 -0700 Subject: [PATCH 30/79] remove references to tracking PRs --- src/feature-lifecycle/stabilization.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 2b3f9f6..e7c3603 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -33,11 +33,11 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization + tracking PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. -You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization + tracking PR [#94640](https://github.com/rust-lang/rust/pull/94640). +You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization PR [#94640](https://github.com/rust-lang/rust/pull/94640). ## When there's `const` involved @@ -103,7 +103,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. -0. (Optional) For partial stabilizations, create a new partial stabilization + tracking PR for the subset of the issue being stabilized under a newly introduced feature name. +0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From 0e08aaf57fcd8165decfef00884587aaaec08baa Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 09:53:06 -0700 Subject: [PATCH 31/79] reframe well-tested comment around API design --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index e7c3603..f1d7e19 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -9,7 +9,7 @@ Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracki ## When is an FCP appropriate? -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization. +Once an unstable feature's API design space (e.g. alternative APIs) has been fully explored with no outstanding concerns, anyone may push for its stabilization. If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. From 80723b99f64b6aa4c4c0b5f551bc07a83b0f1fdc Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 14 Mar 2022 11:55:17 -0700 Subject: [PATCH 32/79] direct people to the exact nightly version rather than forge --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index f1d7e19..1af678d 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -68,7 +68,7 @@ You'll need to change that to a `#[stable]` attribute with a version: #[stable(feature = "total_cmp", since = "1.61.0")] ``` -Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [the forge](https://forge.rust-lang.org/#current-release-versions). Specifically, you'll want to use the version labelled "Nightly". That's two versions higher than the current stable release, as what's currently in beta will be the next stable release, and any change you're making now will be in the one after that. +Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. Specifically, you'll want to use the version labelled "Nightly". That's two versions higher than the current stable release, as what's currently in beta will be the next stable release, and any change you're making now will be in the one after that. ### Remove feature gates from doctests @@ -105,7 +105,7 @@ To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). -0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly in [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the master branch of `rust-lang/rust`. 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. 0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. 0. Open a PR against `rust-lang/rust`. From 26a65de7306a07b5402bcdabe260307be4b2214a Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 16 Mar 2022 11:42:59 -0700 Subject: [PATCH 33/79] remove recommendation on partial stabilization feature names --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 1af678d..15f09a6 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -33,7 +33,7 @@ This will save you from opening a stabilization PR and having it need regular re ## Partial Stabilizations -When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. When you're splitting up the feature, you should always introduce a new feature name for the portion being stabilized and leave the existing feature for the portions left unstable, that way existing users of that feature are not left in a broken state. +When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. @@ -103,7 +103,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. -0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized under a newly introduced feature name. +0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly in [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the master branch of `rust-lang/rust`. 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. From accbcbc2cda50ed8f836fbbae908016f31fb7d6c Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Wed, 16 Mar 2022 14:18:42 -0700 Subject: [PATCH 34/79] integrate additional feedback from libs-api team meeting --- src/feature-lifecycle/stabilization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 15f09a6..aed22af 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -15,13 +15,13 @@ If you're unsure if a feature is ready for stabilization the first step should b ## Stabilization Report -Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. +Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports are not mandatory but they are heavily encouraged, and may be mandated by library API team members if they feel it necessary. The purpose of stabilization reports is to help reviewers more quickly make decisions and to simplify the process of documenting stabilized APIs in release notes. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. -The **Experience Report** section should include links to projects that use the feature being stabilized, or when applicable, projects that use crates that export the same API and describe the experience of using the feature in question. +The **Experience Report** section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized. You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). From 405a608fec07a1a7368e747116237dae85bd5f00 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 21 Mar 2022 16:01:37 -0700 Subject: [PATCH 35/79] fix line that said to ping libs instead of libs-api --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index aed22af..ee764c8 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -27,7 +27,7 @@ You can see examples of stabilization reports in tracking issues [#88581](https: ## Before writing a PR to stabilize a feature -Check to see if a FCP has completed first. 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 first. If not, either ping `@rust-lang/libs-api` or leave a comment asking about the status of the feature. This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course. From edf30acda94d99f86c8e85d462ce39a734c9ddf4 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Mon, 4 Apr 2022 16:07:48 +0200 Subject: [PATCH 36/79] Update membership.md --- src/membership.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/membership.md b/src/membership.md index 0c22dea..5453e05 100644 --- a/src/membership.md +++ b/src/membership.md @@ -16,7 +16,7 @@ and have already been involved in relevant library work. In all cases, the process of adding a new members goes as follows: -1. A member of the Library (API) Team proposes the addition of a contributor on our private mailing list. +1. A member of the Library (API) Team proposes the addition of a contributor on our private Zulip channel. This proposal includes: - A short description of what this person has been working on; how they have been contributing. - A few specific examples of cases where this person clearly communicated their ideas. From 56f2d1bc1da767868e6dc3e1ea761dc23c78ec27 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 12:34:44 -0700 Subject: [PATCH 37/79] Update src/feature-lifecycle/stabilization.md Co-authored-by: Josh Triplett --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index ee764c8..b4dd479 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -5,7 +5,7 @@ Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP[^1] process, which occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP[^1] process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. ## When is an FCP appropriate? From 31712eae69d2ce6255203ed94a76e335e50f6050 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 12:59:31 -0700 Subject: [PATCH 38/79] final cleanup for publication --- src/feature-lifecycle/stabilization.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index b4dd479..e5d60a4 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -1,11 +1,11 @@ # Stabilizing features * **Status:** Current -* **Last Updated:** 2022-03-10 +* **Last Updated:** 2022-05-27 Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP[^1] process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP (Final Comment Period) process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. ## When is an FCP appropriate? @@ -19,11 +19,13 @@ Once a feature is ready for stabilization the first step of the FCP process is w The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved. -The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. +The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in some situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. + +The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. The **Experience Report** section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized. -You can see examples of stabilization reports in tracking issues [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118) and [#29553](https://github.com/rust-lang/rust/issues/29553). +You can see an example of a stabilization report in [#88581](https://github.com/rust-lang/rust/issues/88581#issuecomment-1054642118). ## Before writing a PR to stabilize a feature @@ -68,7 +70,7 @@ You'll need to change that to a `#[stable]` attribute with a version: #[stable(feature = "total_cmp", since = "1.61.0")] ``` -Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. Specifically, you'll want to use the version labelled "Nightly". That's two versions higher than the current stable release, as what's currently in beta will be the next stable release, and any change you're making now will be in the one after that. +Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. ### Remove feature gates from doctests @@ -114,5 +116,3 @@ To stabilize a feature, follow these steps: You can see an example of stabilizing a feature with [tracking issue #81656 with FCP](https://github.com/rust-lang/rust/issues/81656) and the associated [implementation PR #84642](https://github.com/rust-lang/rust/pull/84642). -[^1]: FCP stands for final comment period - From 6ff6d8e5e10a366deb61a5a1772909fbe7c2e3e2 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 14:31:54 -0700 Subject: [PATCH 39/79] add safety comments section to top level summary --- src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c48ccf8..16d15ba 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -42,6 +42,7 @@ - [Documentation](./documentation/summary.md) - [doc alias policy](./documentation/doc-alias-policy.md) + - [safety comments policy](./documentation/safety-comments.md) --- From 08525e0b7426719e415cce44c6bd2cb3f16c1582 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 14:35:48 -0700 Subject: [PATCH 40/79] ignore examples that don't compile without impl blocks --- src/documentation/safety-comments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/documentation/safety-comments.md b/src/documentation/safety-comments.md index 5cbe19d..f47544d 100644 --- a/src/documentation/safety-comments.md +++ b/src/documentation/safety-comments.md @@ -17,7 +17,7 @@ lint for `# Safety` sections by the way. [See the example on github][as_bytes_mut] -```rust +```rust,ignore /// Converts a mutable string slice to a mutable byte slice. /// /// # Safety @@ -64,7 +64,7 @@ not check for `0` before dividing. [See the example on github][split_at] -```rust +```rust,ignore pub fn split_at(&self, mid: usize) -> (&str, &str) { // is_char_boundary checks that the index is in [0, .len()] if self.is_char_boundary(mid) { From 7642673d5b43845a7aedfdc951a655de899dd945 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Fri, 27 May 2022 14:36:58 -0700 Subject: [PATCH 41/79] bump mdbook version to silence warning in CI --- .env | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.env b/.env index aba142f..84f2d46 100644 --- a/.env +++ b/.env @@ -1,4 +1,4 @@ -MDBOOK_VERSION=0.4.8 +MDBOOK_VERSION=0.4.18 MDBOOK_LINKCHECK_VERSION=0.7.4 MDBOOK_TOC_VERSION=0.6.3 From b8a94775fed85851080ee2eb7483742e891633e7 Mon Sep 17 00:00:00 2001 From: The 8472 Date: Sat, 11 Dec 2021 15:18:39 +0100 Subject: [PATCH 42/79] How to printf-debug alloc/core --- src/SUMMARY.md | 5 +++ src/development/building-and-debugging.md | 38 +++++++++++++++++++++++ 2 files changed, 43 insertions(+) create mode 100644 src/development/building-and-debugging.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 16d15ba..252eb12 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,6 +9,11 @@ - [Membership](./membership.md) - [Reviewing](./reviewing.md) +--- + +- [Building and debugging libraries](./development/building-and-debugging.md) + + --- - [The feature lifecycle](./feature-lifecycle/summary.md) diff --git a/src/development/building-and-debugging.md b/src/development/building-and-debugging.md new file mode 100644 index 0000000..5b4f91a --- /dev/null +++ b/src/development/building-and-debugging.md @@ -0,0 +1,38 @@ + +# Building and Debugging the library crates + +Most of the [instructions from the rustc-dev-guide][rustc-guide] also apply to the standard library since +it is built with the same build system, so it is recommended to read it first. + +[rustc-guide]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html + +# Println-debugging alloc and core + +Since logging and IO APIs are not available in `alloc` and `core` advice meant for the rest of the compiler +is not applicable here. + +Instead one can either extract the code that should be tested to a normal crate and add debugging statements there or +on POSIX systems one can use the following hack: + +```rust +extern "C" { + fn dprintf(fd: i32, s: *const u8, ...); +} + +macro_rules! dbg_printf { + ($s:expr) => { + unsafe { dprintf(2, "%s\0".as_ptr(), $s as *const u8); } + } +} + +fn function_to_debug() { + let dbg_str = format!("debug: {}\n\0", "hello world"); + dbg_printf!(dbg_str.as_bytes().as_ptr()); +} +``` + +Then one can run a test which exercises the code to debug and show the error output via + +```shell,ignore +./x.py test library/alloc --test-args --test-args --no-capture +``` \ No newline at end of file From 7f7029de9fe14dd7723efe20302714fd54d65da1 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 30 May 2022 15:17:12 +0200 Subject: [PATCH 43/79] Add explanations on how to write documentation for std/core --- src/SUMMARY.md | 1 + .../how-to-write-documentation.md | 149 ++++++++++++++++++ src/documentation/summary.md | 1 + 3 files changed, 151 insertions(+) create mode 100644 src/documentation/how-to-write-documentation.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 252eb12..91d48b2 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -48,6 +48,7 @@ - [Documentation](./documentation/summary.md) - [doc alias policy](./documentation/doc-alias-policy.md) - [safety comments policy](./documentation/safety-comments.md) + - [how to write documentation](./how-to-write-documentation.md) --- diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md new file mode 100644 index 0000000..d3827ee --- /dev/null +++ b/src/documentation/how-to-write-documentation.md @@ -0,0 +1,149 @@ +# How to write documentation + +This document explains how to write documentation for the std/core public APIs. + +Let's start with some general information: + +### Contractions + +It is common in English to have contractions such as "don't" or "can't". Do not +use these in documentation. Always write their "full form": + + * "do not" instead of "don't" + * "cannot" instead of "can't" + * "it would" instead of "it'd" + * "it will" instead of "it'll" + * "it is"/"it has" instead of "it's" + * "you are" instead of "you're" + * "they are" instead of "they're" + * etc + +The only exception to this rule is "let's" as it is specific/known/common enough. + +The reason is simply to make the reading simpler for as many people as possible. + +### When to use inline code blocks + +Whenever you are talking about a type or anything code related, it should be in a +inline code block. As a reminder, a inline code block is created with backticks +(\`). For example: + + +```text +This a `Vec` and it has a method `push` which you can call by doing `Vec::push`. +``` + +### When to use intra-doc links + +Intra-doc links (you can see the full explanations for the feature +[here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html)) +should be used as much as possible whenever a type is mentioned. + +Little note: when you are documenting an item, no need to link to it. So if you +write documentation for `String::push_str` method, no need to link to the method +`push_str` or to the `String` type. + +If you have cases like `Vec`, you need to use intra-doc links on both +`Vec` and `String` as well. It would look like this: + +```text +This is a [`Vec`]`<`[`String`]`>`. +``` + +Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>` +should as well, otherwise it would render badly. + +### Code blocks + +With rustdoc, code blocks are tested (because they are treated as Rust code +blocks by default). It allows us to know if the documentation is up to date. As +such, please avoid using `ignore` as much as possible on code blocks! If you +want as a language other than Rust, simply set it in the code block tags: + + ```text + This is not rust code! + ``` + +Some special cases: + * If the code example cannot be run (when documenting a I/O item for example), + use `no_run`. + * If it is expected to fail, use `should_panic`. + * If it is expected to fail compilation (which be quite rare!), use `compile_fail`. + +You can find more information about code blocks +[here](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html). + +## How to write documentation for a module + +A module is supposed to contain "similar" items. As such, its documentation is +supposed to give an overview and eventually **a base** to understand what the +items it contains are doing. + +You can take a look at the +[f32 module](https://doc.rust-lang.org/nightly/std/f32/index.html) or at the +[fmt module](https://doc.rust-lang.org/nightly/std/fmt/index.html) to see +good examples. + +## How to write documentation for functions/methods + +The basic format of each documented methods/functions should roughly look like this: + +```text +[explanations] + +[example(s)] +``` + +### Explanations + +By `explanations` we mean that the text should explain what the method and what +each of its arguments are for. Let's take this method for example: + +```rust +pub fn concat_str(&self, s: &str) -> String { + if s.is_empty() { + panic!("empty concat string"); + } + format!("{}{}", self.string, s) +} +``` + +The explanation should look like this: + +```text +Returns a new [`String`] which contains `&self` content with `s` added at the end. +``` + +### Panic? + +If the function/method can panic in certain circumstances, it must to be +mentioned! This explanation needs to be prepended by a `Panics` title: + +```text +# Panics + +`concat_str` panics if `s` is empty. +``` + +### Examples + +As for the examples, they have to show the usage of the function/method. Just +like the `panic` section, they need to be prepended by a `Examples` title. + +It is better if you use `assert*!` macros at the end to ensure that the example +is working as expected. It also allows the readers to understand more easily +what the function is doing (or returning). + + # Examples + + ``` + let s = MyType::new("hello "); + assert_eq!("hello Georges", s.concat_str("Georges").as_str()); + ``` + +## How to write documentation for other items + +It is mostly the same as for methods and functions except that the examples +are (strongly) recommended and not mandatory. + +A good example often shows how to create the item. diff --git a/src/documentation/summary.md b/src/documentation/summary.md index 686bcac..c1311a2 100644 --- a/src/documentation/summary.md +++ b/src/documentation/summary.md @@ -1,2 +1,3 @@ - [doc alias policy](./doc-alias-policy.md) - [safety comments policy](./safety-comments.md) +- [how to write documentation](./how-to-write-documentation.md) From ff0461e634214be28c24356838bb48930d82943f Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 30 May 2022 15:29:03 +0200 Subject: [PATCH 44/79] Add guideline about "reviewing doc changes" --- src/SUMMARY.md | 1 + src/documentation/reviewing-doc-changes.md | 24 ++++++++++++++++++++++ src/documentation/summary.md | 1 + 3 files changed, 26 insertions(+) create mode 100644 src/documentation/reviewing-doc-changes.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 91d48b2..7a07dad 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -49,6 +49,7 @@ - [doc alias policy](./documentation/doc-alias-policy.md) - [safety comments policy](./documentation/safety-comments.md) - [how to write documentation](./how-to-write-documentation.md) + - [reviewing doc changes](./reviewing-doc-changes.md) --- diff --git a/src/documentation/reviewing-doc-changes.md b/src/documentation/reviewing-doc-changes.md new file mode 100644 index 0000000..810dec3 --- /dev/null +++ b/src/documentation/reviewing-doc-changes.md @@ -0,0 +1,24 @@ +# 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 + +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 +example: + + * Showing precisely how a function on floats handles `NaN`. + * Saying that a sort method has a particular running-time bound. + +So if a doc change updates/adds/removes a stability guarantee, it has to be +**very** carefully handled and needs to go through the +[libs API team FCP](https://rustc-dev-guide.rust-lang.org/stabilization_guide.html?highlight=fcp#fcp). + +It can be circumvented by adding a `# Current Implementation` section +[like done here](https://github.com/rust-lang/rust/blob/4a8d2e3856c0c75c71998b6c85937203839b946d/library/alloc/src/slice.rs#L250). diff --git a/src/documentation/summary.md b/src/documentation/summary.md index c1311a2..acd7b98 100644 --- a/src/documentation/summary.md +++ b/src/documentation/summary.md @@ -1,3 +1,4 @@ - [doc alias policy](./doc-alias-policy.md) - [safety comments policy](./safety-comments.md) - [how to write documentation](./how-to-write-documentation.md) +- [reviewing doc changes](./reviewing-doc-changes.md) From 7bf55a807dc173421ffeb3f42ab6aaf99ed709a9 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 31 May 2022 15:56:40 -0700 Subject: [PATCH 45/79] fix broken links --- src/SUMMARY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 7a07dad..ea8164f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -48,8 +48,8 @@ - [Documentation](./documentation/summary.md) - [doc alias policy](./documentation/doc-alias-policy.md) - [safety comments policy](./documentation/safety-comments.md) - - [how to write documentation](./how-to-write-documentation.md) - - [reviewing doc changes](./reviewing-doc-changes.md) + - [how to write documentation](./documentation/how-to-write-documentation.md) + - [reviewing doc changes](./documentation/reviewing-doc-changes.md) --- From 0b89f946bb586f77ad803decda0200f23389d638 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 2 Jun 2022 11:32:54 +0200 Subject: [PATCH 46/79] Fix code blocks --- .../how-to-write-documentation.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index d3827ee..2c88147 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -60,9 +60,11 @@ blocks by default). It allows us to know if the documentation is up to date. As such, please avoid using `ignore` as much as possible on code blocks! If you want as a language other than Rust, simply set it in the code block tags: - ```text - This is not rust code! - ``` +````text +```text +This is not rust code! +``` +```` Some special cases: * If the code example cannot be run (when documenting a I/O item for example), @@ -99,7 +101,7 @@ The basic format of each documented methods/functions should roughly look like t By `explanations` we mean that the text should explain what the method and what each of its arguments are for. Let's take this method for example: -```rust +```rust,ignore pub fn concat_str(&self, s: &str) -> String { if s.is_empty() { panic!("empty concat string"); @@ -134,12 +136,14 @@ It is better if you use `assert*!` macros at the end to ensure that the example is working as expected. It also allows the readers to understand more easily what the function is doing (or returning). - # Examples +````text +# Examples - ``` - let s = MyType::new("hello "); - assert_eq!("hello Georges", s.concat_str("Georges").as_str()); - ``` +``` +let s = MyType::new("hello "); +assert_eq!("hello Georges", s.concat_str("Georges").as_str()); +``` +```` ## How to write documentation for other items From 5ed4edd012be49e2ec8d5662212564b7e53a68e6 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 1 Jun 2022 16:00:04 +0200 Subject: [PATCH 47/79] Updates on "how to write documentation" --- src/documentation/how-to-write-documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index 2c88147..9679a9b 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -39,9 +39,9 @@ Intra-doc links (you can see the full explanations for the feature [here](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html)) should be used as much as possible whenever a type is mentioned. -Little note: when you are documenting an item, no need to link to it. So if you -write documentation for `String::push_str` method, no need to link to the method -`push_str` or to the `String` type. +Little note: when you are documenting an item, there is no need to link to it. +So, if you write documentation for the `String::push_str` method, there is +no need to link to the `push_str` method or the `String` type. If you have cases like `Vec`, you need to use intra-doc links on both `Vec` and `String` as well. It would look like this: From ac6554bcd800d14b46c6475c3b9041487f2e1f95 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 2 Jun 2022 16:59:53 +0200 Subject: [PATCH 48/79] Remove controversial parts of "how to write documentation" --- .../how-to-write-documentation.md | 33 ++----------------- 1 file changed, 3 insertions(+), 30 deletions(-) diff --git a/src/documentation/how-to-write-documentation.md b/src/documentation/how-to-write-documentation.md index 9679a9b..eac10ab 100644 --- a/src/documentation/how-to-write-documentation.md +++ b/src/documentation/how-to-write-documentation.md @@ -4,24 +4,6 @@ This document explains how to write documentation for the std/core public APIs. Let's start with some general information: -### Contractions - -It is common in English to have contractions such as "don't" or "can't". Do not -use these in documentation. Always write their "full form": - - * "do not" instead of "don't" - * "cannot" instead of "can't" - * "it would" instead of "it'd" - * "it will" instead of "it'll" - * "it is"/"it has" instead of "it's" - * "you are" instead of "you're" - * "they are" instead of "they're" - * etc - -The only exception to this rule is "let's" as it is specific/known/common enough. - -The reason is simply to make the reading simpler for as many people as possible. - ### When to use inline code blocks Whenever you are talking about a type or anything code related, it should be in a @@ -43,16 +25,6 @@ Little note: when you are documenting an item, there is no need to link to it. So, if you write documentation for the `String::push_str` method, there is no need to link to the `push_str` method or the `String` type. -If you have cases like `Vec`, you need to use intra-doc links on both -`Vec` and `String` as well. It would look like this: - -```text -This is a [`Vec`]`<`[`String`]`>`. -``` - -Extra explanations: since both `Vec` and `String` are in codeblocks, `<` and `>` -should as well, otherwise it would render badly. - ### Code blocks With rustdoc, code blocks are tested (because they are treated as Rust code @@ -130,14 +102,15 @@ mentioned! This explanation needs to be prepended by a `Panics` title: ### Examples As for the examples, they have to show the usage of the function/method. Just -like the `panic` section, they need to be prepended by a `Examples` title. +like the `panic` section, they need to be prepended by a `Example` title (plural +if there is more than one). It is better if you use `assert*!` macros at the end to ensure that the example is working as expected. It also allows the readers to understand more easily what the function is doing (or returning). ````text -# Examples +# Example ``` let s = MyType::new("hello "); From a5c72a2c65b45b332047ec4074db89416b0706b3 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 6 Jun 2022 15:37:28 -0700 Subject: [PATCH 49/79] Document the new ACP process --- src/SUMMARY.md | 2 +- src/feature-lifecycle/api-change-proposals.md | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 src/feature-lifecycle/api-change-proposals.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index ea8164f..5b0860d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -17,7 +17,7 @@ --- - [The feature lifecycle](./feature-lifecycle/summary.md) - - [Landing new features](./feature-lifecycle/new-unstable-features.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) diff --git a/src/feature-lifecycle/api-change-proposals.md b/src/feature-lifecycle/api-change-proposals.md new file mode 100644 index 0000000..878cad4 --- /dev/null +++ b/src/feature-lifecycle/api-change-proposals.md @@ -0,0 +1,21 @@ +# API Change Proposals (ACP) + +Changes to the standard library's unstable API go through the libs ACP process. + +The API Change Proposal process is intended to be a lightweight first step to +getting new APIs added to the standard library. The goal of this process is to +make sure proposed API changes have the best chance of success. The ACP process +accomplishes this by ensuring all changes have had a libs-api team member +second the proposal indicating that they are optimistic that the proposal will +pass its eventual FCP and by focusing the initial discussion on the problems +being solved and concrete motivating examples. + +You can create an ACP in the `rust-lang/libs-team` repo using [this issue template](https://github.com/rust-lang/libs-team/issues/new?assignees=&labels=api-change-proposal%2C+T-libs-api&template=api-change-proposal.md&title=%28My+API+Change+Proposal%29). + +Once a t-libs-api team member has reviewed the ACP and judged that it should +move forward they will second the ACP (via `@rfcbot second`) and initiate an +ICP (inital comment period). This initial comment period is intended to give +other stake holders a chance to participate in the initial discussion prior to +starting the implementation. Once this ICP has completed you should proceed +with the implementation of your proposal and then move on to the next step of +the feature lifecycle, creating a tracking issue. From 91eaf7e3f0d0c29772e1a7a122298d6b7ce52114 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Mon, 6 Jun 2022 15:40:38 -0700 Subject: [PATCH 50/79] actually remove old unstable features doc --- src/feature-lifecycle/new-unstable-features.md | 11 ----------- 1 file changed, 11 deletions(-) delete mode 100644 src/feature-lifecycle/new-unstable-features.md diff --git a/src/feature-lifecycle/new-unstable-features.md b/src/feature-lifecycle/new-unstable-features.md deleted file mode 100644 index faa9076..0000000 --- a/src/feature-lifecycle/new-unstable-features.md +++ /dev/null @@ -1,11 +0,0 @@ -# Landing new features - -**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. - -If you're not sure, open an issue against `rust-lang/rust` first suggesting the feature before developing it. - -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). From a0a5dc714d02eca656fc89dcbecd1e4e9836ecf0 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 7 Jun 2022 13:03:05 -0700 Subject: [PATCH 51/79] remove reference to unsupported command --- src/feature-lifecycle/api-change-proposals.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/feature-lifecycle/api-change-proposals.md b/src/feature-lifecycle/api-change-proposals.md index 878cad4..f16680b 100644 --- a/src/feature-lifecycle/api-change-proposals.md +++ b/src/feature-lifecycle/api-change-proposals.md @@ -13,9 +13,9 @@ being solved and concrete motivating examples. You can create an ACP in the `rust-lang/libs-team` repo using [this issue template](https://github.com/rust-lang/libs-team/issues/new?assignees=&labels=api-change-proposal%2C+T-libs-api&template=api-change-proposal.md&title=%28My+API+Change+Proposal%29). Once a t-libs-api team member has reviewed the ACP and judged that it should -move forward they will second the ACP (via `@rfcbot second`) and initiate an -ICP (inital comment period). This initial comment period is intended to give -other stake holders a chance to participate in the initial discussion prior to -starting the implementation. Once this ICP has completed you should proceed -with the implementation of your proposal and then move on to the next step of -the feature lifecycle, creating a tracking issue. +move forward they will second the ACP and initiate an ICP (inital comment +period). This initial comment period is intended to give other stake holders a +chance to participate in the initial discussion prior to starting the +implementation. Once this ICP has completed you should proceed with the +implementation of your proposal and then move on to the next step of the +feature lifecycle, creating a tracking issue. From f67d0d2ee98794def73d7c7d6e3a5c3e9f97eb6e Mon Sep 17 00:00:00 2001 From: matthewjasper <20113453+matthewjasper@users.noreply.github.com> Date: Fri, 29 Jul 2022 18:33:39 +0100 Subject: [PATCH 52/79] Apply suggestions from code review Co-authored-by: Jane Losare-Lusby --- src/code-considerations/using-unstable-lang/specialization.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/code-considerations/using-unstable-lang/specialization.md b/src/code-considerations/using-unstable-lang/specialization.md index 6385b9a..a8c7054 100644 --- a/src/code-considerations/using-unstable-lang/specialization.md +++ b/src/code-considerations/using-unstable-lang/specialization.md @@ -63,8 +63,9 @@ Only specialization using the `min_specialization` feature should be used. The f There are two unstable attributes that can be used to allow a trait bound in a specializing implementation that does not appear in the default implementation. `rustc_specialization_trait` restricts the implementations of a trait to be "always applicable". Implementing traits annotated with `rustc_specialization_trait` is unstable, so this should not be used on any stable traits exported from the standard library. `Sized` is an exception, and can have this attribute because it already cannot be implemented by an `impl` block. +**Note**: `rustc_specialization_trait` only prevents incorrect monomorphizations, it does not prevent a type from being coerced between specialized and unspecialized types which can be important when specialization must be applied consistently. See [rust-lang/rust#85863](https://github.com/rust-lang/rust/issues/85863) for more details. -`rustc_unsafe_specialization_marker` allows specializing on a trait with no associated items. The attribute is `unsafe` because lifetime constraints from the implementations of the trait are not considered when specializing. In the following example, the specialized implementation is used for *all* shared reference types, not just those with `'static` lifetime. +`rustc_unsafe_specialization_marker` allows specializing on a trait with no associated items. The attribute is `unsafe` because lifetime constraints from the implementations of the trait are not considered when specializing. The following example demonstrates incorrect usage of `rustc_unsafe_specialization_marker`, the specialized implementation is used for *all* shared reference types, not just those with `'static` lifetime. ```rust,ignore #[rustc_unsafe_specialization_marker] From 104f78a99e0679286761b9f1c62a828d3fc21f22 Mon Sep 17 00:00:00 2001 From: Matthew Jasper Date: Fri, 29 Jul 2022 18:54:34 +0100 Subject: [PATCH 53/79] Clarify what example is showing --- src/code-considerations/using-unstable-lang/specialization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/code-considerations/using-unstable-lang/specialization.md b/src/code-considerations/using-unstable-lang/specialization.md index a8c7054..820fe54 100644 --- a/src/code-considerations/using-unstable-lang/specialization.md +++ b/src/code-considerations/using-unstable-lang/specialization.md @@ -65,7 +65,7 @@ There are two unstable attributes that can be used to allow a trait bound in a s `rustc_specialization_trait` restricts the implementations of a trait to be "always applicable". Implementing traits annotated with `rustc_specialization_trait` is unstable, so this should not be used on any stable traits exported from the standard library. `Sized` is an exception, and can have this attribute because it already cannot be implemented by an `impl` block. **Note**: `rustc_specialization_trait` only prevents incorrect monomorphizations, it does not prevent a type from being coerced between specialized and unspecialized types which can be important when specialization must be applied consistently. See [rust-lang/rust#85863](https://github.com/rust-lang/rust/issues/85863) for more details. -`rustc_unsafe_specialization_marker` allows specializing on a trait with no associated items. The attribute is `unsafe` because lifetime constraints from the implementations of the trait are not considered when specializing. The following example demonstrates incorrect usage of `rustc_unsafe_specialization_marker`, the specialized implementation is used for *all* shared reference types, not just those with `'static` lifetime. +`rustc_unsafe_specialization_marker` allows specializing on a trait with no associated items. The attribute is `unsafe` because lifetime constraints from the implementations of the trait are not considered when specializing. The following example demonstrates a limitation of `rustc_unsafe_specialization_marker`, the specialized implementation is used for *all* shared reference types, not just those with `'static` lifetime. Because of this, new uses of `rustc_unsafe_specialization_marker` should be avoided. ```rust,ignore #[rustc_unsafe_specialization_marker] @@ -90,7 +90,7 @@ impl DoThing for T { } ``` -`rustc_unsafe_specialization_marker` exists to allow existing specializations that are based on marker traits exported from `std`, such as `Copy`, `FusedIterator` or `Eq`. New uses of `rustc_unsafe_specialization_marker` should be avoided. +`rustc_unsafe_specialization_marker` exists to allow existing specializations that are based on marker traits exported from `std`, such as `Copy`, `FusedIterator` or `Eq`. ## For reviewers From 125fd7c1cd67525581dc4f964a2e5b79019dcc66 Mon Sep 17 00:00:00 2001 From: est31 Date: Wed, 24 Aug 2022 01:24:42 +0200 Subject: [PATCH 54/79] rustc_deprecated got removed, now only deprecated is used See https://github.com/rust-lang/rust/pull/95960 --- src/feature-lifecycle/deprecation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/deprecation.md b/src/feature-lifecycle/deprecation.md index 68b90a4..e5523db 100644 --- a/src/feature-lifecycle/deprecation.md +++ b/src/feature-lifecycle/deprecation.md @@ -2,6 +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. +Public APIs aren't deleted from the standard library. If something shouldn't be used anymore it gets deprecated by adding a `#[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. From 0a20475e24d8bccfd3abb8c85fd4e76f76a296d6 Mon Sep 17 00:00:00 2001 From: est31 Date: Wed, 24 Aug 2022 01:29:06 +0200 Subject: [PATCH 55/79] Update the library stabilization guide to refer to the new placeholder system --- src/feature-lifecycle/stabilization.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index e5d60a4..438263b 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -64,13 +64,13 @@ Library items are marked unstable via the `#[unstable]` attribute, like this: pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { ... } ``` -You'll need to change that to a `#[stable]` attribute with a version: +You'll need to change that to a `#[stable]` attribute with the version set to the placeholder `CURRENT_RUSTC_VERSION`: ```rust,ignore -#[stable(feature = "total_cmp", since = "1.61.0")] +#[stable(feature = "total_cmp", since = "CURRENT_RUSTC_VERSION")] ``` -Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the current master branch of `rust-lang/rust`. +Note that other `#[stable]` attributes may contain spelled out version numbers, but you should not spell out any version number as it might get outdated by the time your pull request merges. ### Remove feature gates from doctests @@ -107,9 +107,9 @@ To stabilize a feature, follow these steps: 0. Create a stabiliation report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). -0. Change `#[unstable(...)]` to `#[stable(since = "version")]`. `version` should be the *current nightly*, i.e. stable+2. You can see which version is the current nightly in [`src/version`](https://github.com/rust-lang/rust/blob/master/src/version) on the master branch of `rust-lang/rust`. +0. Change `#[unstable(...)]` to `#[stable(since = "CURRENT_RUSTC_VERSION")]`. `CURRENT_RUSTC_VERSION` here is meant in a literal sense and not to be replaced with the spelled out version number. 0. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. -0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "version")]`. +0. If applicable, change `#[rustc_const_unstable(...)]` to `#[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")]`. 0. Open a PR against `rust-lang/rust`. - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. - Link to the tracking issue by adding "Closes #XXXXX". From 737cdb1a1434ddea28bb78cf7214dcc6cebc8725 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Mon, 12 Sep 2022 12:10:33 +0200 Subject: [PATCH 56/79] Fix small typo in stabilization guide --- src/feature-lifecycle/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 438263b..3722f8e 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -104,7 +104,7 @@ The compiler builds with nightly features allowed, so you may find uses of the f To stabilize a feature, follow these steps: -0. Create a stabiliation report in the tracking issue for the feature being stabilized. +0. Create a stabilization report in the tracking issue for the feature being stabilized. 0. (Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized. 0. Ask a **@rust-lang/libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). 0. Change `#[unstable(...)]` to `#[stable(since = "CURRENT_RUSTC_VERSION")]`. `CURRENT_RUSTC_VERSION` here is meant in a literal sense and not to be replaced with the spelled out version number. From 365cf150b62094c0aacb1fab67ed9863228b3399 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Sun, 8 Jan 2023 11:35:53 +0900 Subject: [PATCH 57/79] Replace outdated highfive links Signed-off-by: Yuki Okushi --- src/feature-lifecycle/stabilization.md | 9 +++++---- src/reviewing.md | 2 +- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/src/feature-lifecycle/stabilization.md b/src/feature-lifecycle/stabilization.md index 3722f8e..ec8b964 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/feature-lifecycle/stabilization.md @@ -11,7 +11,7 @@ Stabilization goes through the Libs FCP (Final Comment Period) process, which ty Once an unstable feature's API design space (e.g. alternative APIs) has been fully explored with no outstanding concerns, anyone may push for its stabilization. -If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +If you're unsure if a feature is ready for stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/rust/blob/master/triagebot.toml) directly to request assistance. ## Stabilization Report @@ -21,7 +21,7 @@ The **Implementation History** section should summarize the initial discussion d The **API Summary** section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in some situations it may not be possible to edit the original tracking issue to fix outdated information, such as when the author of the stabilization report is not the author of the tracking issue itself. -The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs. +The libs team maintains a tool for this called [`cargo unstable-api`](https://github.com/rust-lang/libs-team/tree/main/tools/unstable-api) that can be used to generate these API summaries in some cases. *Note* the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built on top of either rustdoc or rustc's own APIs. The **Experience Report** section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized. @@ -29,7 +29,8 @@ You can see an example of a stabilization report in [#88581](https://github.com/ ## Before writing a PR to stabilize a feature -Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs-api` or leave a comment asking about the status of the feature. +Check to see if a FCP has completed first. If not, either ping `@rust-lang/libs-api` if you're a member of the `rust-lang` organization, +or leave a comment asking about the status of the feature. This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course. @@ -37,7 +38,7 @@ This will save you from opening a stabilization PR and having it need regular re When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized. -If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json) directly to request assistance. +If you're unsure if a feature is ready for partial stabilization the first step should be to ask in the relevant tracking issue and get assistance from other participants in that discussion. In some cases the tracking issue may not have many other active participants, so if you're ever having trouble getting any feedback please ping one of the [libs team reviewers](https://github.com/rust-lang/rust/blob/master/triagebot.toml) directly to request assistance. You can see an example of partially stabilizing a feature with tracking issue [#71146](https://github.com/rust-lang/rust/issues/71146) and partial stabilization PR [#94640](https://github.com/rust-lang/rust/pull/94640). diff --git a/src/reviewing.md b/src/reviewing.md index a6535f8..567c6d9 100644 --- a/src/reviewing.md +++ b/src/reviewing.md @@ -33,4 +33,4 @@ use `r? rust-lang/libs`. If you find yourself unable to do any reviews for an extended period of time, it might be a good idea to (temporarily) remove yourself from the list. To add or remove yourself from the list, send a PR to change the -[high-five configuration file](https://github.com/rust-lang/highfive/blob/master/highfive/configs/rust-lang/rust.json). +[triagebot configuration file](https://github.com/rust-lang/rust/blob/master/triagebot.toml). From 340be06277fcf6893d58ab7e66309432340553af Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 9 Jan 2023 06:45:47 +0900 Subject: [PATCH 58/79] Use the latest Ubuntu image Signed-off-by: Yuki Okushi --- .github/workflows/ci.yml | 20 ++++++++++---------- .github/workflows/gh-pages.yml | 10 +++++----- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b517a0b..76f69e0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,7 +7,7 @@ on: jobs: book-test: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v2 @@ -18,7 +18,7 @@ jobs: echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" - + - name: Cache binaries id: mdbook-cache uses: actions/cache@v2 @@ -31,12 +31,12 @@ jobs: if: steps.mdbook-cache.outputs.cache-hit != 'true' uses: actions-rs/toolchain@v1 with: - toolchain: stable - override: true + toolchain: stable + override: true - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' - run: | + run: | cargo install mdbook --version ${{ steps.mdbook-version.outputs.MDBOOK_VERSION }} cargo install mdbook-linkcheck --version ${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }} cargo install mdbook-toc --version ${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} @@ -45,7 +45,7 @@ jobs: run: mdbook test book-build: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v2 @@ -56,7 +56,7 @@ jobs: echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" - + - name: Cache binaries id: mdbook-cache uses: actions/cache@v2 @@ -69,12 +69,12 @@ jobs: if: steps.mdbook-cache.outputs.cache-hit != 'true' uses: actions-rs/toolchain@v1 with: - toolchain: stable - override: true + toolchain: stable + override: true - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' - run: | + run: | cargo install mdbook --version ${{ steps.mdbook-version.outputs.MDBOOK_VERSION }} cargo install mdbook-linkcheck --version ${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }} cargo install mdbook-toc --version ${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 7200c48..2c526c4 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -7,7 +7,7 @@ on: jobs: deploy: - runs-on: ubuntu-20.04 + runs-on: ubuntu-22.04 steps: - uses: actions/checkout@v2 @@ -18,7 +18,7 @@ jobs: echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" - + - name: Cache binaries id: mdbook-cache uses: actions/cache@v2 @@ -31,12 +31,12 @@ jobs: if: steps.mdbook-cache.outputs.cache-hit != 'true' uses: actions-rs/toolchain@v1 with: - toolchain: stable - override: true + toolchain: stable + override: true - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' - run: | + run: | cargo install mdbook --version ${{ steps.mdbook-version.outputs.MDBOOK_VERSION }} cargo install mdbook-linkcheck --version ${{ steps.mdbook-version.outputs.MDBOOK_LINKCHECK_VERSION }} cargo install mdbook-toc --version ${{ steps.mdbook-version.outputs.MDBOOK_TOC_VERSION }} From acdc58ba676f2e6c234524cccc374d7e96b9f536 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 9 Jan 2023 06:46:27 +0900 Subject: [PATCH 59/79] Use v3 for actions/{cache,checkout} Signed-off-by: Yuki Okushi --- .github/workflows/ci.yml | 8 ++++---- .github/workflows/gh-pages.yml | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 76f69e0..f63a10a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -9,7 +9,7 @@ jobs: book-test: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Read .env id: mdbook-version @@ -21,7 +21,7 @@ jobs: - name: Cache binaries id: mdbook-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.cargo/bin @@ -47,7 +47,7 @@ jobs: book-build: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Read .env id: mdbook-version @@ -59,7 +59,7 @@ jobs: - name: Cache binaries id: mdbook-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.cargo/bin diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2c526c4..505c0b9 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -9,7 +9,7 @@ jobs: deploy: runs-on: ubuntu-22.04 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - name: Read .env id: mdbook-version @@ -21,7 +21,7 @@ jobs: - name: Cache binaries id: mdbook-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.cargo/bin From cd1e2f8d32b33e5a8490f2f34ba20583ab4cf528 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 9 Jan 2023 06:48:09 +0900 Subject: [PATCH 60/79] Remove unmaintained action Signed-off-by: Yuki Okushi --- .github/workflows/ci.yml | 14 ++++++-------- .github/workflows/gh-pages.yml | 7 +++---- 2 files changed, 9 insertions(+), 12 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f63a10a..8401bd0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,10 +29,9 @@ jobs: - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + run: | + rustup update stable + rustup override set stable - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' @@ -67,10 +66,9 @@ jobs: - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + run: | + rustup update stable + rustup override set stable - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 505c0b9..60b3ccc 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -29,10 +29,9 @@ jobs: - name: Install latest stable Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' - uses: actions-rs/toolchain@v1 - with: - toolchain: stable - override: true + run: | + rustup update stable + rustup override set stable - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' From cf214838337745cf31b4df44b24cd2dabfe8eb2e Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 9 Jan 2023 06:50:44 +0900 Subject: [PATCH 61/79] Remove deprecated `set-output`s Signed-off-by: Yuki Okushi --- .github/workflows/ci.yml | 12 ++++++------ .github/workflows/gh-pages.yml | 6 +++--- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8401bd0..986079c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,9 +15,9 @@ jobs: id: mdbook-version run: | . ./.env - echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" - echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" - echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" + echo "MDBOOK_VERSION=${MDBOOK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_LINKCHECK_VERSION=${MDBOOK_LINKCHECK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_TOC_VERSION=${MDBOOK_TOC_VERSION}" >> $GITHUB_OUTPUT - name: Cache binaries id: mdbook-cache @@ -52,9 +52,9 @@ jobs: id: mdbook-version run: | . ./.env - echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" - echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" - echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" + echo "MDBOOK_VERSION=${MDBOOK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_LINKCHECK_VERSION=${MDBOOK_LINKCHECK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_TOC_VERSION=${MDBOOK_TOC_VERSION}" >> $GITHUB_OUTPUT - name: Cache binaries id: mdbook-cache diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 60b3ccc..4979d06 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -15,9 +15,9 @@ jobs: id: mdbook-version run: | . ./.env - echo "::set-output name=MDBOOK_VERSION::${MDBOOK_VERSION}" - echo "::set-output name=MDBOOK_LINKCHECK_VERSION::${MDBOOK_LINKCHECK_VERSION}" - echo "::set-output name=MDBOOK_TOC_VERSION::${MDBOOK_TOC_VERSION}" + echo "MDBOOK_VERSION=${MDBOOK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_LINKCHECK_VERSION=${MDBOOK_LINKCHECK_VERSION}" >> $GITHUB_OUTPUT + echo "MDBOOK_TOC_VERSION=${MDBOOK_TOC_VERSION}" >> $GITHUB_OUTPUT - name: Cache binaries id: mdbook-cache From 27c4d79ca2d51f788635282397e7b939daa10679 Mon Sep 17 00:00:00 2001 From: Yuki Okushi Date: Mon, 9 Jan 2023 06:54:19 +0900 Subject: [PATCH 62/79] Upgrade mdbook-related dependencies Signed-off-by: Yuki Okushi --- .env | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.env b/.env index 84f2d46..4fd08c4 100644 --- a/.env +++ b/.env @@ -1,6 +1,6 @@ -MDBOOK_VERSION=0.4.18 -MDBOOK_LINKCHECK_VERSION=0.7.4 -MDBOOK_TOC_VERSION=0.6.3 +MDBOOK_VERSION=0.4.25 +MDBOOK_LINKCHECK_VERSION=0.7.7 +MDBOOK_TOC_VERSION=0.11.0 GIT_DEPLOY_DIR=book/html GIT_DEPLOY_BRANCH=gh-pages From c40fa93cff20a025e5ef75e6c328a2690eb268b3 Mon Sep 17 00:00:00 2001 From: Praveen Kumar Date: Thu, 19 Jan 2023 13:16:46 +0530 Subject: [PATCH 63/79] fixed a typo in 'r++ permission' description. --- src/team.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/team.md b/src/team.md index 5e01dac..d74aebd 100644 --- a/src/team.md +++ b/src/team.md @@ -49,7 +49,7 @@ See [Membership](./membership.md) for details. ### r+ permission All members of the Library Team, the Library API Team, and the Library Contributors -have the permission to approve PRs, and are expected handle this with care. +have the permission to approve PRs, and are expected to handle this with care. See [Reviewing](./reviewing.md) for details. ### high-five rotation From fbb1d076c739d8c7b43fe171259cc2bf3c33d4b6 Mon Sep 17 00:00:00 2001 From: The 8472 Date: Mon, 3 Oct 2022 13:56:33 +0200 Subject: [PATCH 64/79] add a page on optimizations and profiling --- src/SUMMARY.md | 1 + src/development/perf-benchmarking.md | 117 +++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 src/development/perf-benchmarking.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 5b0860d..955f7fa 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -12,6 +12,7 @@ --- - [Building and debugging libraries](./development/building-and-debugging.md) +- [Performance optimizations and benchmarking](./development/perf-benchmarking.md) --- diff --git a/src/development/perf-benchmarking.md b/src/development/perf-benchmarking.md new file mode 100644 index 0000000..c232019 --- /dev/null +++ b/src/development/perf-benchmarking.md @@ -0,0 +1,117 @@ +# Library optimizations and benchmarking + +Recommended reading: [The Rust performance book](https://nnethercote.github.io/perf-book/title-page.html) + +## What to optimize + +It's preferred to optimize code that shows up as significant in real-world code. +E.g. it's more beneficial to speed up `[T]::sort` than it is to shave off a small allocation in `Command::spawn` +because the latter is dominated by its syscall cost. + +Issues about slow library code are labeled as [I-slow T-libs](https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AI-slow+label%3AT-libs) +and those about code size as [I-heavy T-libs](https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AI-heavy+label%3AT-libs) + +## Vectorization + +Currently explicit SIMD features can't be used in alloc or core because runtime feature-detection is only available in std +and they are compiled with each target's baseline feature set. + +Vectorization can only be achieved by shaping code in a way that the compiler backend's auto-vectorization passes can understand. + +## rustc-perf + +For parts of the standard library that are heavily used by rustc itself it can be convenient to use +[the benchmark server](https://github.com/rust-lang/rustc-perf/tree/master/collector#benchmarking). + +Since it only measures compile-time but not runtime performance of crates it can't be used to benchmark for features +that aren't used by the compiler, e.g. floating point code, linked lists, mpsc channels, etc. +For those explicit benchmarks must be written or extracted from real-world code. + +## Built-in Microbenchmarks + +The built-in benchmarks use [cargo bench](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +and can be found in the `benches` directory for `core` and `alloc` and in `test` modules in `std`. + +The benchmarks are automatically executed run in a loop by `Bencher::iter` to average the runtime over many loop-iterations. +For CPU-bound microbenchmarks the runtime of a single iteration should be in the range of nano- to microseconds. + +To run a specific can be invoked without recompiling rustc +via `./x bench library/ --stage 0 --test-args `. + +`cargo bench` measures wall-time. This often is good enough, but small changes such as saving a few instructions +in a bigger function can get drowned out by system noise. In such cases the following changes can make runs more +reproducible: + +* disable incremental builds in `config.toml` +* build std and the benchmarks with `RUSTFLAGS_BOOTSTRAP="-Ccodegen-units=1"` +* ensure the system is as idle as possible +* [disable ASLR](https://man7.org/linux/man-pages/man8/setarch.8.html) +* [pinning](https://man7.org/linux/man-pages/man1/taskset.1.html) the benchmark process to a specific core +* [disable clock boosts](https://wiki.archlinux.org/title/CPU_frequency_scaling#Configuring_frequency_boosting), + especially on thermal-limited systems such as laptops + +## Standalone tests + +If `x` or the cargo benchmark harness get in the way it can be useful to extract the benchmark into a separate crate, +e.g. to run it under `perf stat` or cachegrind. + +Build and link the [stage1](https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#creating-a-rustup-toolchain) +compiler as rustup toolchain and then use that to build the standalone benchmark with a modified standard library. + +[Currently](https://github.com/rust-lang/rust/issues/101691) there is no convenient way to invoke a stage0 toolchain with +a modified standard library. To avoid the compiler rebuild it can be useful to not only extract the benchmark but also +the code under test into a separate crate. + +## Running under perf-record + +If extracting the code into a separate crate is impractical one can first build the benchmark and then run it again +under `perf record` and then drill down to the benchmark kernel with `perf report`. + +```terminal,ignore +# 1CGU to reduce inlining changes and code reorderings, debuginfo for source annotations +$ export RUSTFLAGS_BOOTSTRAP="-Ccodegen-units=1 -Cdebuginfo=2" + +# build benchmark without running it +$ ./x bench --stage 0 library/core/ --test-args skipallbenches + +# run the benchmark under perf +$ perf record --call-graph dwarf -e instructions ./x bench --stage 0 library/core/ --test-args +$ perf report +``` + +By renaming `perf.data` to keep it from getting overwritten by subsequent runs it can be later compared to runs with +a modified library with `perf diff`. + +## comparing assembly + +While `perf report` shows assembly of the benchmark code it can sometimes be difficult to get a good overview of what +changed, especially when multiple benchmarks were affected. As an alternative one can extract and diff the assembly +directly from the benchmark suite. + +```terminal,ignore +# 1CGU to reduce inlining changes and code reorderings, debuginfo for source annotations +$ export RUSTFLAGS_BOOTSTRAP="-Ccodegen-units=1 -Cdebuginfo=2" + +# build benchmark libs +$ ./x bench --stage 0 library/core/ --test-args skipallbenches + +# this should print something like the following +Running benches/lib.rs (build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps/corebenches-2199e9a22e7b1f4a) + +# get the assembly for all the benchmarks +$ objdump --source --disassemble --wide --no-show-raw-insn --no-addresses \ + build/x86_64-unknown-linux-gnu/stage0-std/x86_64-unknown-linux-gnu/release/deps/corebenches-2199e9a22e7b1f4a \ + | rustfilt > baseline.asm + +# switch to the branch with the changes +$ git switch feature-branch + +# repeat the procedure above +$ ./x bench ... +$ objdump ... > changes.asm + +# compare output +$ kdiff3 baseline.asm changes.asm +``` + +This can also be applied to standalone benchmarks. From 722cb2fbc61f87182bd6a6d575390a164034130c Mon Sep 17 00:00:00 2001 From: The 8472 Date: Sat, 18 Feb 2023 15:38:31 +0100 Subject: [PATCH 65/79] - reword vectorization section - mention scaling governors - linking stage0 as rustup toolchain is now supported --- src/development/perf-benchmarking.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/src/development/perf-benchmarking.md b/src/development/perf-benchmarking.md index c232019..dcbb611 100644 --- a/src/development/perf-benchmarking.md +++ b/src/development/perf-benchmarking.md @@ -13,10 +13,11 @@ and those about code size as [I-heavy T-libs](https://github.com/rust-lang/rust/ ## Vectorization -Currently explicit SIMD features can't be used in alloc or core because runtime feature-detection is only available in std -and they are compiled with each target's baseline feature set. - -Vectorization can only be achieved by shaping code in a way that the compiler backend's auto-vectorization passes can understand. +Currently only baseline target features (e.g. SSE2 on x86_64-unknown-linux-gnu) can be used in core and alloc because +runtime feature-detection is only available in std. +Where possible the preferred way to achieve vectorization is by shaping code in a way that the compiler +backend's auto-vectorization passes can understand. This benefits user crates compiled with additional target features +when they instantiate generic library functions, e.g. iterators. ## rustc-perf @@ -47,6 +48,8 @@ reproducible: * ensure the system is as idle as possible * [disable ASLR](https://man7.org/linux/man-pages/man8/setarch.8.html) * [pinning](https://man7.org/linux/man-pages/man1/taskset.1.html) the benchmark process to a specific core +* change the CPU [scaling governor](https://wiki.archlinux.org/title/CPU_frequency_scaling#Scaling_governors) + to a fixed-frequency one (`performance` or `powersave`) * [disable clock boosts](https://wiki.archlinux.org/title/CPU_frequency_scaling#Configuring_frequency_boosting), especially on thermal-limited systems such as laptops @@ -55,11 +58,10 @@ reproducible: If `x` or the cargo benchmark harness get in the way it can be useful to extract the benchmark into a separate crate, e.g. to run it under `perf stat` or cachegrind. -Build and link the [stage1](https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#creating-a-rustup-toolchain) -compiler as rustup toolchain and then use that to build the standalone benchmark with a modified standard library. +Build the standard library and link [stage0-sysroot](https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html#creating-a-rustup-toolchain) +as rustup toolchain and then use that to build the standalone benchmark with a modified standard library. -[Currently](https://github.com/rust-lang/rust/issues/101691) there is no convenient way to invoke a stage0 toolchain with -a modified standard library. To avoid the compiler rebuild it can be useful to not only extract the benchmark but also +If the std rebuild times are too long for fast iteration it can be useful to not only extract the benchmark but also the code under test into a separate crate. ## Running under perf-record From addb3ba3580db84cb327015e817fbeec2713654c Mon Sep 17 00:00:00 2001 From: Noam Ta Shma Date: Sat, 4 Mar 2023 14:09:27 +0200 Subject: [PATCH 66/79] fix an extra hyphen --- src/development/building-and-debugging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/development/building-and-debugging.md b/src/development/building-and-debugging.md index 5b4f91a..9922ad8 100644 --- a/src/development/building-and-debugging.md +++ b/src/development/building-and-debugging.md @@ -34,5 +34,5 @@ fn function_to_debug() { Then one can run a test which exercises the code to debug and show the error output via ```shell,ignore -./x.py test library/alloc --test-args --test-args --no-capture +./x.py test library/alloc --test-args --test-args --nocapture ``` \ No newline at end of file From f1557839969606dcf86205d0ec42c258e3dd4ee8 Mon Sep 17 00:00:00 2001 From: Harrison Hemstreet <65803282+HarrisonHemstreet@users.noreply.github.com> Date: Tue, 16 May 2023 19:53:09 -0600 Subject: [PATCH 67/79] fixed grammar in team.md --- src/team.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/team.md b/src/team.md index d74aebd..fa4cee1 100644 --- a/src/team.md +++ b/src/team.md @@ -32,7 +32,7 @@ of breaking changes and how they are avoided. ## The Library Contributors -In addition to the two teams above, we also have a the Library Contributors, +In addition to the two teams above, we also have the Library Contributors, which is a somewhat more loosely defined team consisting of those who regularly contribute or review changes to the standard libraries. From 283a56b6bde009ea4d6771df0c84f662c447ba2b Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 24 Jun 2023 17:24:13 +0200 Subject: [PATCH 68/79] Move team pages into team/. --- src/SUMMARY.md | 8 ++++---- src/{ => team}/meetings.md | 0 src/{ => team}/membership.md | 0 src/{ => team}/reviewing.md | 0 src/{team.md => team/summary.md} | 0 5 files changed, 4 insertions(+), 4 deletions(-) rename src/{ => team}/meetings.md (100%) rename src/{ => team}/membership.md (100%) rename src/{ => team}/reviewing.md (100%) rename src/{team.md => team/summary.md} (100%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 955f7fa..c51f4fb 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -4,10 +4,10 @@ [Getting started](./getting-started.md) -- [The library team](./team.md) - - [Meetings](./meetings.md) - - [Membership](./membership.md) - - [Reviewing](./reviewing.md) +- [The library team](./team/summary.md) + - [Meetings](./team/meetings.md) + - [Membership](./team/membership.md) + - [Reviewing](./team/reviewing.md) --- diff --git a/src/meetings.md b/src/team/meetings.md similarity index 100% rename from src/meetings.md rename to src/team/meetings.md diff --git a/src/membership.md b/src/team/membership.md similarity index 100% rename from src/membership.md rename to src/team/membership.md diff --git a/src/reviewing.md b/src/team/reviewing.md similarity index 100% rename from src/reviewing.md rename to src/team/reviewing.md diff --git a/src/team.md b/src/team/summary.md similarity index 100% rename from src/team.md rename to src/team/summary.md From 0278893fdd2ee22915673a29efa596e888a6e34f Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 24 Jun 2023 17:27:01 +0200 Subject: [PATCH 69/79] Remove tools and bots section. There's almost no information in there. We can add it back when we have anything useful to say. --- src/SUMMARY.md | 7 ------- src/tools-and-bots/bors.md | 15 --------------- src/tools-and-bots/crater.md | 23 ----------------------- src/tools-and-bots/summary.md | 3 --- src/tools-and-bots/timer.md | 9 --------- 5 files changed, 57 deletions(-) delete mode 100644 src/tools-and-bots/bors.md delete mode 100644 src/tools-and-bots/crater.md delete mode 100644 src/tools-and-bots/summary.md delete mode 100644 src/tools-and-bots/timer.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c51f4fb..c64a529 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -51,10 +51,3 @@ - [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) diff --git a/src/tools-and-bots/bors.md b/src/tools-and-bots/bors.md deleted file mode 100644 index 3a213de..0000000 --- a/src/tools-and-bots/bors.md +++ /dev/null @@ -1,15 +0,0 @@ -# `@bors` - -**Status:** Stub - -PRs to the standard library aren’t merged manually using GitHub’s UI or by pushing remote branches. Everything goes through [`@bors`](https://github.com/rust-lang/homu). - -You can approve a PR with: - -```ignore -@bors r+ -``` - -## Rolling up - -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.html#rollups) for more details on when to rollup. diff --git a/src/tools-and-bots/crater.md b/src/tools-and-bots/crater.md deleted file mode 100644 index 990c499..0000000 --- a/src/tools-and-bots/crater.md +++ /dev/null @@ -1,23 +0,0 @@ -# `@craterbot` - -**Status:** Stub - -[Crater](https://github.com/rust-lang/crater) is a tool that can test PRs against a public subset of the Rust ecosystem to estimate the scale of potential breakage. - -You can kick off a crater run by first calling: - -```ignore -@bors try -``` - -Once that finishes, you can then call: - -```ignore -@craterbot check -``` - -to ensure crates compile, or: - -```ignore -@craterbot run mode=build-and-test -``` diff --git a/src/tools-and-bots/summary.md b/src/tools-and-bots/summary.md deleted file mode 100644 index 6a76859..0000000 --- a/src/tools-and-bots/summary.md +++ /dev/null @@ -1,3 +0,0 @@ -# Tools and bots - -**Status:** Stub diff --git a/src/tools-and-bots/timer.md b/src/tools-and-bots/timer.md deleted file mode 100644 index 2f7c9b3..0000000 --- a/src/tools-and-bots/timer.md +++ /dev/null @@ -1,9 +0,0 @@ -# `@rust-timer` - -**Status:** Stub - -You can kick off a performance test using `@rust-timer`: - -```ignore -@bors try @rust-timer queue -``` From 9c201b6dc5559d7f1a5db743e9fb161d597e6d3b Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Sat, 24 Jun 2023 18:36:52 +0200 Subject: [PATCH 70/79] Reorganise and clean up the whole guide. --- book.toml | 3 + src/SUMMARY.md | 75 ++++++--------- src/about-this-guide.md | 19 ---- src/about.md | 13 +++ .../doc-changes.md} | 11 +-- src/breaking-changes/new-trait-impls.md | 93 +++++++++++++++++++ .../breaking-changes/prelude.md | 9 +- src/breaking-changes/summary.md | 8 ++ .../breaking-changes/behavior.md | 9 -- .../breaking-changes/fundamental.md | 31 ------- .../breaking-changes/new-trait-impls.md | 76 --------------- .../breaking-changes/summary.md | 17 ---- src/code-considerations/design/public-apis.md | 9 -- src/code-considerations/design/summary.md | 9 -- .../performance/summary.md | 9 -- .../mem-and-exclusive-refs.md | 15 --- .../safety-and-soundness/summary.md | 13 --- src/code-considerations/summary.md | 11 --- .../using-unstable-lang/const-generics.md | 25 ----- .../using-unstable-lang/summary.md | 11 --- .../how-to-write-documentation.md | 0 .../stabilization.md | 2 +- src/documentation/summary.md | 4 - src/feature-lifecycle/api-change-proposals.md | 21 ----- src/feature-lifecycle/deprecation.md | 7 -- src/feature-lifecycle/summary.md | 3 - src/feature-lifecycle/tracking-issues.md | 16 ---- src/getting-started.md | 27 ------ .../doc-alias.md} | 0 .../performance => policy}/inline.md | 0 .../design => policy}/must-use.md | 0 .../safety-comments.md | 0 .../specialization.md | 4 - .../generics-and-unsafe.md | 0 .../may-dangle.md | 0 35 files changed, 151 insertions(+), 399 deletions(-) delete mode 100644 src/about-this-guide.md create mode 100644 src/about.md rename src/{documentation/reviewing-doc-changes.md => breaking-changes/doc-changes.md} (69%) create mode 100644 src/breaking-changes/new-trait-impls.md rename src/{code-considerations => }/breaking-changes/prelude.md (56%) create mode 100644 src/breaking-changes/summary.md delete mode 100644 src/code-considerations/breaking-changes/behavior.md delete mode 100644 src/code-considerations/breaking-changes/fundamental.md delete mode 100644 src/code-considerations/breaking-changes/new-trait-impls.md delete mode 100644 src/code-considerations/breaking-changes/summary.md delete mode 100644 src/code-considerations/design/public-apis.md delete mode 100644 src/code-considerations/design/summary.md delete mode 100644 src/code-considerations/performance/summary.md delete mode 100644 src/code-considerations/safety-and-soundness/mem-and-exclusive-refs.md delete mode 100644 src/code-considerations/safety-and-soundness/summary.md delete mode 100644 src/code-considerations/summary.md delete mode 100644 src/code-considerations/using-unstable-lang/const-generics.md delete mode 100644 src/code-considerations/using-unstable-lang/summary.md rename src/{documentation => development}/how-to-write-documentation.md (100%) rename src/{feature-lifecycle => development}/stabilization.md (98%) delete mode 100644 src/documentation/summary.md delete mode 100644 src/feature-lifecycle/api-change-proposals.md delete mode 100644 src/feature-lifecycle/deprecation.md delete mode 100644 src/feature-lifecycle/summary.md delete mode 100644 src/feature-lifecycle/tracking-issues.md delete mode 100644 src/getting-started.md rename src/{documentation/doc-alias-policy.md => policy/doc-alias.md} (100%) rename src/{code-considerations/performance => policy}/inline.md (100%) rename src/{code-considerations/design => policy}/must-use.md (100%) rename src/{documentation => policy}/safety-comments.md (100%) rename src/{code-considerations/using-unstable-lang => policy}/specialization.md (94%) rename src/{code-considerations/safety-and-soundness => tricky}/generics-and-unsafe.md (100%) rename src/{code-considerations/safety-and-soundness => tricky}/may-dangle.md (100%) diff --git a/book.toml b/book.toml index 4699954..32e2684 100644 --- a/book.toml +++ b/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" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c64a529..04b8a62 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,53 +1,30 @@ # Summary -[About this guide](./about-this-guide.md) - -[Getting started](./getting-started.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) - ---- - -- [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) + - [Meetings](./team/meetings.md) + - [Membership](./team/membership.md) + - [Reviewing](./team/reviewing.md) diff --git a/src/about-this-guide.md b/src/about-this-guide.md deleted file mode 100644 index f096a63..0000000 --- a/src/about-this-guide.md +++ /dev/null @@ -1,19 +0,0 @@ -# About this guide - -**Status:** Stub - -This guide is for contributors and reviewers to Rust's standard library. - -## Other places to find information - -You might also find the following sites useful: - -- [std API docs] -- rustdoc documentation for the standard library itself -- [Forge] -- contains documentation about rust infrastructure, team procedures, and more -- [libs-team] -- the home-base for the rust Library Team, with description - of the team procedures, active working groups, and the team calendar. - -[GitHub repository]: https://github.com/rust-lang/std-dev-guide/ -[std API docs]: https://doc.rust-lang.org/nightly/std/ -[Forge]: https://forge.rust-lang.org/ -[libs-team]: https://github.com/rust-lang/libs-team/ diff --git a/src/about.md b/src/about.md new file mode 100644 index 0000000..f39e210 --- /dev/null +++ b/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/ diff --git a/src/documentation/reviewing-doc-changes.md b/src/breaking-changes/doc-changes.md similarity index 69% rename from src/documentation/reviewing-doc-changes.md rename to src/breaking-changes/doc-changes.md index 810dec3..79abbcc 100644 --- a/src/documentation/reviewing-doc-changes.md +++ b/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 diff --git a/src/breaking-changes/new-trait-impls.md b/src/breaking-changes/new-trait-impls.md new file mode 100644 index 0000000..33d4cf8 --- /dev/null +++ b/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 { .. } +``` + +```rust,ignore +// in an external `lib` +let b = Arc::from("a"); +``` + +then we add: + +```diff +impl From<&str> for Arc { .. } ++ impl From<&str> for Arc { .. } +``` + +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`. + +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 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` +- `Pin` + +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 diff --git a/src/code-considerations/breaking-changes/prelude.md b/src/breaking-changes/prelude.md similarity index 56% rename from src/code-considerations/breaking-changes/prelude.md rename to src/breaking-changes/prelude.md index 6c4a4d0..cf38517 100644 --- a/src/code-considerations/breaking-changes/prelude.md +++ b/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). diff --git a/src/breaking-changes/summary.md b/src/breaking-changes/summary.md new file mode 100644 index 0000000..9368382 --- /dev/null +++ b/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. diff --git a/src/code-considerations/breaking-changes/behavior.md b/src/code-considerations/breaking-changes/behavior.md deleted file mode 100644 index 09aac4d..0000000 --- a/src/code-considerations/breaking-changes/behavior.md +++ /dev/null @@ -1,9 +0,0 @@ -# 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](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. - -## For reviewers - -Look out for changes in existing implementations for stable functions, especially if assertions in test cases have been changed. diff --git a/src/code-considerations/breaking-changes/fundamental.md b/src/code-considerations/breaking-changes/fundamental.md deleted file mode 100644 index b3f3841..0000000 --- a/src/code-considerations/breaking-changes/fundamental.md +++ /dev/null @@ -1,31 +0,0 @@ -# `#[fundamental]` types - -**Status:** Stub - -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` -- `Pin` - -Typically, the scope of [breakage in new trait impls](./new-trait-impls.md) 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 - -## For reviewers - -Look out for blanket trait implementations for fundamental types, like: - -```rust,ignore -impl<'a, T> PublicTrait for &'a T -where - T: SomeBound, -{ - -} -``` - -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]: ../../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 deleted file mode 100644 index a42d41f..0000000 --- a/src/code-considerations/breaking-changes/new-trait-impls.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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. The following sections gives some examples of breakage from new trait impls that may not be obvious just from the change made to the standard library. - -Also see [`#[fundamental]` types](./fundamental.md) for special considerations for types like `&T`, `&mut T`, `Box`, and other core smart pointers. - -## 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 { .. } -``` - -```rust,ignore -// in an external `lib` -let b = Arc::from("a"); -``` - -then we add: - -```diff -impl From<&str> for Arc { .. } -+ impl From<&str> for Arc { .. } -``` - -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`. - -This kind of breakage can be ok, but a [crater](../../tools-and-bots/crater.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 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](../../tools-and-bots/crater.md) run should estimate the scope. - -## For reviewers - -Look out for new `#[stable]` trait implementations for existing stable traits. diff --git a/src/code-considerations/breaking-changes/summary.md b/src/code-considerations/breaking-changes/summary.md deleted file mode 100644 index 34073b7..0000000 --- a/src/code-considerations/breaking-changes/summary.md +++ /dev/null @@ -1,17 +0,0 @@ -# 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](../../tools-and-bots/crater.md) run. - -There are strategies for mitigating breakage depending on the impact. - -For changes where the value is high and the impact is high too: - -- Using compiler lints to try phase out broken behavior. - -If the impact isn't too high: - -- Looping in maintainers of broken crates and submitting PRs to fix them. - -## 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 deleted file mode 100644 index 47964d4..0000000 --- a/src/code-considerations/design/public-apis.md +++ /dev/null @@ -1,9 +0,0 @@ -# Public API design - -**Status:** Stub - -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 - -For new unstable features, look for any prior discussion of the proposed API to see what options and tradeoffs have already been considered. If in doubt, ping `@rust-lang/libs` for input. diff --git a/src/code-considerations/design/summary.md b/src/code-considerations/design/summary.md deleted file mode 100644 index c75e174..0000000 --- a/src/code-considerations/design/summary.md +++ /dev/null @@ -1,9 +0,0 @@ -# Design - -**Status:** Stub - -Most of the considerations in this guide are quality in some sense. This section has some general advice on maintaining code quality in the standard library. - -## For reviewers - -Think about how you would implement a feature and whether your approach would differ from what's being proposed. What trade-offs are being made? Is the weighting of those trade-offs the most appropriate? diff --git a/src/code-considerations/performance/summary.md b/src/code-considerations/performance/summary.md deleted file mode 100644 index 21745a0..0000000 --- a/src/code-considerations/performance/summary.md +++ /dev/null @@ -1,9 +0,0 @@ -# Performance - -**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`](../../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`. 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 deleted file mode 100644 index 633e063..0000000 --- a/src/code-considerations/safety-and-soundness/mem-and-exclusive-refs.md +++ /dev/null @@ -1,15 +0,0 @@ -# Using `mem` to break assumptions - -## `mem::replace` and `mem::swap` - -Any value behind a `&mut` reference can be replaced with a new one using `mem::replace` or `mem::swap`, so code shouldn't assume any reachable mutable references can't have their internals changed by replacing. - -## `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](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](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 - -If there's a `Drop` impl involved, look out for possible soundness issues that could come from that destructor never running. diff --git a/src/code-considerations/safety-and-soundness/summary.md b/src/code-considerations/safety-and-soundness/summary.md deleted file mode 100644 index 3ef1520..0000000 --- a/src/code-considerations/safety-and-soundness/summary.md +++ /dev/null @@ -1,13 +0,0 @@ -# Safety and soundness - -**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 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](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. - -Look at the level of test coverage for the new unsafe code. Tests do catch bugs! diff --git a/src/code-considerations/summary.md b/src/code-considerations/summary.md deleted file mode 100644 index fb6618f..0000000 --- a/src/code-considerations/summary.md +++ /dev/null @@ -1,11 +0,0 @@ -# Code considerations - -Code considerations capture our experiences working on the standard library for all contributors. If you come across something new or unexpected then a code consideration is a great place to record it. Then other contributors and reviewers can find it by searching the guide. - -## How to write a code consideration - -Code considerations are a bit like guidelines. They should try make concrete recommendations that reviewers and contributors can refer to in discussions. A link to a real case where this was discussed or tripped us up is good to include. - -Code considerations should also try include a _For reviewers_ section. These can call out specific things to look out for in reviews that could suggest the consideration applies. They can also include advice on how to apply it. - -It's more important that we capture these experiences _somehow_ though, so don't be afraid to drop some sketchy notes in and debate the details later! diff --git a/src/code-considerations/using-unstable-lang/const-generics.md b/src/code-considerations/using-unstable-lang/const-generics.md deleted file mode 100644 index 15a0312..0000000 --- a/src/code-considerations/using-unstable-lang/const-generics.md +++ /dev/null @@ -1,25 +0,0 @@ -# Using const generics - -**Status:** Stub - -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 - -Look out for const operations on const generics in public APIs like: - -```rust,ignore -pub fn extend_array(arr: [T; N]) -> [T; N + 1] { - .. -} -``` - -or for const generics that aren't integers, bools, or chars: - -```rust,ignore -pub fn tag() { - .. -} -``` diff --git a/src/code-considerations/using-unstable-lang/summary.md b/src/code-considerations/using-unstable-lang/summary.md deleted file mode 100644 index d97acf5..0000000 --- a/src/code-considerations/using-unstable-lang/summary.md +++ /dev/null @@ -1,11 +0,0 @@ -# Using unstable language features - -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](./const-generics.md) -- [Specialization](./specialization.md) -- _Something missing?_ Please submit a PR to keep this list up-to-date! - -## For reviewers - -Look out for any use of unstable language features in PRs, especially if any new `#![feature]` attributes have been added. diff --git a/src/documentation/how-to-write-documentation.md b/src/development/how-to-write-documentation.md similarity index 100% rename from src/documentation/how-to-write-documentation.md rename to src/development/how-to-write-documentation.md diff --git a/src/feature-lifecycle/stabilization.md b/src/development/stabilization.md similarity index 98% rename from src/feature-lifecycle/stabilization.md rename to src/development/stabilization.md index ec8b964..5adf6c3 100644 --- a/src/feature-lifecycle/stabilization.md +++ b/src/development/stabilization.md @@ -5,7 +5,7 @@ Feature stabilization involves adding `#[stable]` attributes. They may be introduced alongside new trait impls or replace existing `#[unstable]` attributes. -Stabilization goes through the Libs FCP (Final Comment Period) process, which typically occurs on the [tracking issue](./tracking-issues.md) for the feature. +Stabilization goes through the Libs FCP (Final Comment Period) process, which typically occurs on the tracking issue for the feature. ## When is an FCP appropriate? diff --git a/src/documentation/summary.md b/src/documentation/summary.md deleted file mode 100644 index acd7b98..0000000 --- a/src/documentation/summary.md +++ /dev/null @@ -1,4 +0,0 @@ -- [doc alias policy](./doc-alias-policy.md) -- [safety comments policy](./safety-comments.md) -- [how to write documentation](./how-to-write-documentation.md) -- [reviewing doc changes](./reviewing-doc-changes.md) diff --git a/src/feature-lifecycle/api-change-proposals.md b/src/feature-lifecycle/api-change-proposals.md deleted file mode 100644 index f16680b..0000000 --- a/src/feature-lifecycle/api-change-proposals.md +++ /dev/null @@ -1,21 +0,0 @@ -# API Change Proposals (ACP) - -Changes to the standard library's unstable API go through the libs ACP process. - -The API Change Proposal process is intended to be a lightweight first step to -getting new APIs added to the standard library. The goal of this process is to -make sure proposed API changes have the best chance of success. The ACP process -accomplishes this by ensuring all changes have had a libs-api team member -second the proposal indicating that they are optimistic that the proposal will -pass its eventual FCP and by focusing the initial discussion on the problems -being solved and concrete motivating examples. - -You can create an ACP in the `rust-lang/libs-team` repo using [this issue template](https://github.com/rust-lang/libs-team/issues/new?assignees=&labels=api-change-proposal%2C+T-libs-api&template=api-change-proposal.md&title=%28My+API+Change+Proposal%29). - -Once a t-libs-api team member has reviewed the ACP and judged that it should -move forward they will second the ACP and initiate an ICP (inital comment -period). This initial comment period is intended to give other stake holders a -chance to participate in the initial discussion prior to starting the -implementation. Once this ICP has completed you should proceed with the -implementation of your proposal and then move on to the next step of the -feature lifecycle, creating a tracking issue. diff --git a/src/feature-lifecycle/deprecation.md b/src/feature-lifecycle/deprecation.md deleted file mode 100644 index e5523db..0000000 --- a/src/feature-lifecycle/deprecation.md +++ /dev/null @@ -1,7 +0,0 @@ -# Deprecating features - -**Status:** Stub - -Public APIs aren't deleted from the standard library. If something shouldn't be used anymore it gets deprecated by adding a `#[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/summary.md b/src/feature-lifecycle/summary.md deleted file mode 100644 index aadc7e6..0000000 --- a/src/feature-lifecycle/summary.md +++ /dev/null @@ -1,3 +0,0 @@ -# The feature lifecycle - -**Status:** Stub diff --git a/src/feature-lifecycle/tracking-issues.md b/src/feature-lifecycle/tracking-issues.md deleted file mode 100644 index 082938d..0000000 --- a/src/feature-lifecycle/tracking-issues.md +++ /dev/null @@ -1,16 +0,0 @@ -# Using tracking issues - -**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. - -## Creating a tracking issue - -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. - -## Working on an unstable feature - -The current state of an unstable feature should be outlined in its tracking issue. - -If there's a change you'd like to make to an unstable feature, it can be discussed on the tracking issue first. - diff --git a/src/getting-started.md b/src/getting-started.md deleted file mode 100644 index 92ce024..0000000 --- a/src/getting-started.md +++ /dev/null @@ -1,27 +0,0 @@ -# Getting started - -**Status:** Stub - -Welcome to the standard library! - -This guide is an effort to capture some of the context needed to develop and maintain the Rust standard library. Its goal is to help members of the Libs team share the process and experience they bring to working on the standard library so other members can benefit. It’ll probably accumulate a lot of trivia that might also be interesting to members of the wider Rust community. - -## Where to get help - -Maintaining the standard library can feel like a daunting responsibility! - -Ping the `@rust-lang/libs-impl` or `@rust-lang/libs` teams on GitHub anytime. - -You can also reach out in the [`t-libs` stream on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/219381-t-libs/). - -## A tour of the standard library - -**Status:** Stub - -The standard library codebase lives in the [`rust-lang/rust`](https://github.com/rust-lang/rust) repository under the `/library` directory. - -The standard library is made up of three crates that exist in a loose hierarchy: - -- `core`: dependency free and makes minimal assumptions about the runtime environment. -- `alloc`: depends on `core`, assumes allocator support. `alloc` doesn't re-export `core`'s public API, so it's not strictly above it in the layering. -- `std`: depends on `core` and `alloc` and re-exports both of their public APIs. diff --git a/src/documentation/doc-alias-policy.md b/src/policy/doc-alias.md similarity index 100% rename from src/documentation/doc-alias-policy.md rename to src/policy/doc-alias.md diff --git a/src/code-considerations/performance/inline.md b/src/policy/inline.md similarity index 100% rename from src/code-considerations/performance/inline.md rename to src/policy/inline.md diff --git a/src/code-considerations/design/must-use.md b/src/policy/must-use.md similarity index 100% rename from src/code-considerations/design/must-use.md rename to src/policy/must-use.md diff --git a/src/documentation/safety-comments.md b/src/policy/safety-comments.md similarity index 100% rename from src/documentation/safety-comments.md rename to src/policy/safety-comments.md diff --git a/src/code-considerations/using-unstable-lang/specialization.md b/src/policy/specialization.md similarity index 94% rename from src/code-considerations/using-unstable-lang/specialization.md rename to src/policy/specialization.md index 820fe54..fd698b4 100644 --- a/src/code-considerations/using-unstable-lang/specialization.md +++ b/src/policy/specialization.md @@ -91,7 +91,3 @@ impl DoThing for T { ``` `rustc_unsafe_specialization_marker` exists to allow existing specializations that are based on marker traits exported from `std`, such as `Copy`, `FusedIterator` or `Eq`. - -## For reviewers - -Look out for any `default` annotations on public trait implementations. These will need to be refactored into a private dispatch trait. Also look out for uses of specialization that do more than pick a more optimized implementation. diff --git a/src/code-considerations/safety-and-soundness/generics-and-unsafe.md b/src/tricky/generics-and-unsafe.md similarity index 100% rename from src/code-considerations/safety-and-soundness/generics-and-unsafe.md rename to src/tricky/generics-and-unsafe.md diff --git a/src/code-considerations/safety-and-soundness/may-dangle.md b/src/tricky/may-dangle.md similarity index 100% rename from src/code-considerations/safety-and-soundness/may-dangle.md rename to src/tricky/may-dangle.md From ced20ea7437f06d858b038bdf0b1c1145ddfd5d5 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Mon, 26 Jun 2023 18:47:43 +0200 Subject: [PATCH 71/79] Add some info for reviewers. --- src/team/reviewing.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/team/reviewing.md b/src/team/reviewing.md index 567c6d9..507a0cf 100644 --- a/src/team/reviewing.md +++ b/src/team/reviewing.md @@ -17,6 +17,8 @@ But please keep in mind: Make sure to involve `@rust-lang/libs-api` on such changes. - Always be polite when reviewing: you are a representative of the Rust project, so it is expected that you will go above and beyond when it comes to the Code of Conduct. +See https://forge.rust-lang.org/compiler/reviews.html for more information on reviewing. + ## High-five rotation Some of the members of the team are part of the 'high-five rotation'; @@ -34,3 +36,12 @@ If you find yourself unable to do any reviews for an extended period of time, it might be a good idea to (temporarily) remove yourself from the list. To add or remove yourself from the list, send a PR to change the [triagebot configuration file](https://github.com/rust-lang/rust/blob/master/triagebot.toml). + +## Rolling up + +For library PRs, rolling up (`@bors r+ rollup`) is often fine, +in particular if it's only a new unstable addition or if it only touches docs. +PRs that impact performance should not be rolled up (`@bors rollup=never`), +PRs with subtle platform specific changes might also not be great candiates for rolling up. +See the [rollup guidelines](https://forge.rust-lang.org/compiler/reviews.html#rollups) for more +details on when to rollup. From cf0a4f6f3a0dbf54d7ca1b685fec73d9b7b48534 Mon Sep 17 00:00:00 2001 From: Mara Bos Date: Mon, 26 Jun 2023 19:04:29 +0200 Subject: [PATCH 72/79] Make links clickable. --- src/about.md | 4 ++-- src/team/reviewing.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/about.md b/src/about.md index f39e210..4b5b1e9 100644 --- a/src/about.md +++ b/src/about.md @@ -9,5 +9,5 @@ Contributions to this guide are very welcome. Other useful documentation: -- https://forge.rust-lang.org/ -- https://rustc-dev-guide.rust-lang.org/ +- +- diff --git a/src/team/reviewing.md b/src/team/reviewing.md index 507a0cf..261cd49 100644 --- a/src/team/reviewing.md +++ b/src/team/reviewing.md @@ -17,7 +17,7 @@ But please keep in mind: Make sure to involve `@rust-lang/libs-api` on such changes. - Always be polite when reviewing: you are a representative of the Rust project, so it is expected that you will go above and beyond when it comes to the Code of Conduct. -See https://forge.rust-lang.org/compiler/reviews.html for more information on reviewing. +See for more information on reviewing. ## High-five rotation From 0a1b50394d289afd4025197ff5af503930832a1d Mon Sep 17 00:00:00 2001 From: Amanieu d'Antras Date: Fri, 19 May 2023 15:45:54 +0200 Subject: [PATCH 73/79] Rework the feature lifecycle --- src/SUMMARY.md | 1 + src/development/feature-lifecycle.md | 57 ++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) create mode 100644 src/development/feature-lifecycle.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 04b8a62..abb0a81 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -6,6 +6,7 @@ - [Building and debugging](./development/building-and-debugging.md) - [Performance optimizations and benchmarking](./development/perf-benchmarking.md) - [Writing documentation](./development/how-to-write-documentation.md) + - [Feature lifecycle](./feature-lifecycle.md) - [Stabilizing a feature](./development/stabilization.md) - [Breaking changes](./breaking-changes/summary.md) diff --git a/src/development/feature-lifecycle.md b/src/development/feature-lifecycle.md new file mode 100644 index 0000000..ce51bce --- /dev/null +++ b/src/development/feature-lifecycle.md @@ -0,0 +1,57 @@ +# The feature lifecycle + +## Identifying the problem + +The first step before proposing any change to the standard library is to properly identify the problem that is trying to be solved. This helps to identify cases of the [XY problem] where a better solution exists without needing any changes to the standard library. + +For this reason it is helpful to focus on real problems that people are encountering, rather than theoretical concerns about API design. + +[XY problem]: https://en.wikipedia.org/wiki/XY_problem + +## Suitability for the standard library + +Unlike third party crates on crates.io, the Rust standard library is not versioned. This means that any stable API that is added can *never* be removed or modified in a backwards-incompatible way. For this reason, the standard library maintainers place a high bar on any change to the standard library API. + +APIs that are well suited to the standard library are things that require language and/or compiler support, or that extend existing standard library types. Complex APIs that are expected to evolve over time (e.g. GUI frameworks) are a poor fit due to the lack of versioning. + +The API Change Proposal process is intended to be a lightweight first step to +getting new APIs added to the standard library. The goal of this process is to +make sure proposed API changes have the best chance of success. The ACP process +accomplishes this by ensuring all changes are reviewed by the library API team, +who will evaluate the proposal and accept it if they are optimistic that the proposal will +be merged and pass its eventual FCP. + +You can create an ACP in the `rust-lang/libs-team` repo using [this issue template](https://github.com/rust-lang/libs-team/issues/new?assignees=&labels=api-change-proposal%2C+T-libs-api&template=api-change-proposal.md&title=%28My+API+Change+Proposal%29). This should include a sketch of the proposed API, but does not have to be the final design that will be implemented. + +Note that an ACP is not strictly required: you can just go ahead and submit a pull request with an implementation of your proposed API, with the risk of wasted effort if the library team ends up rejecting this feature. However do note that this risk is always present even if an ACP is accepted, as the library team can end up rejecting a feature in the later parts of the stabilization process. + +## API design exploration + +Once a feature is deemed suitable for inclusion in the standard library, the exact design should be iterated on to find the best way to express it as a Rust API. This iteration should happen in community forums such as [Rust internals](https://internals.rust-lang.org/) where all members of the community can comment and propose improvements. + +Keep the following points in mind during the discussion: +- Try to achieve a balance between generality and specificity: + - An overly general API tends to be difficult to use for common use cases, and has a complex API surface. This makes it difficult to review and maintain, and it may be a better fit for an external crate. + - An overly specific API does not cover all common use cases, and may require further API changes in the future to accomodate these use cases. +- An alternative that should *always* be considered is simply adding this feature via a third party crate. This is even possible when adding new methods to standard library types by using extension traits. +- In the case of "convenience" functions which are simply shorthands for something that is already possible with existing APIs, the cost of extending the standard library surface should be weighed against the ergonomic impact of the new functions. + - For example, too many convenience methods on a type makes nagivating the documentation more difficult. + - Additionally, consider whether this method is likely to be deprecated in the future if a language-level improvement makes it unnecessary. + +The library team itself is not directly involved in this discussion, but individual members may comment to provide feedback. If significant changes have occurred since the ACP, another one may be proposed at this point to have the design validated by the library API team. + +## Implementation + +Once the API design space has been explored, an implementation based on the favored solution should be proposed as a pull request to the `rust-lang/rust` repository. + +The pull request should include a summary of the alternatives that were considered. This is helpful for reviewers since it avoids duplicating this exploration work as part of the review. A PR submitted without this may be closed with a request to explore more alternatives. + +If an ACP has not been filed for the proposed feature, the PR will need to be reviewed by the library API team to determine its suitability for the standard library. + +## Tracking and stabilization + +Before a PR is merged, you will be asked to open a tracking issue which will track the progress of the feature until its [stabilization](stabilization.md). + +There are two exceptions to this: +- Modifications of an existing unstable API can re-use the existing tracking issue for this API. +- Changes that are instantly stable (e.g. trait implementations on stable types) do not need a tracking issue. However, such changes need extra scrutiny as there will be no chance to adjust the API during an unstable period. From 6e4758e12a17a2dda3dce33c45011876ca7a3df6 Mon Sep 17 00:00:00 2001 From: Amanieu d'Antras Date: Mon, 10 Jul 2023 10:10:17 +0100 Subject: [PATCH 74/79] Fix incorrect link for feature lifecycle. --- src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index abb0a81..aeb1cdf 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -6,7 +6,7 @@ - [Building and debugging](./development/building-and-debugging.md) - [Performance optimizations and benchmarking](./development/perf-benchmarking.md) - [Writing documentation](./development/how-to-write-documentation.md) - - [Feature lifecycle](./feature-lifecycle.md) + - [Feature lifecycle](./development/feature-lifecycle.md) - [Stabilizing a feature](./development/stabilization.md) - [Breaking changes](./breaking-changes/summary.md) From d77c25927c5d6287a539c8e874f3f5ce9abfdb81 Mon Sep 17 00:00:00 2001 From: Mark Rousskov Date: Sat, 20 Jan 2024 16:13:40 -0500 Subject: [PATCH 75/79] Add policy detailing review procedure for target-specific code --- src/SUMMARY.md | 1 + src/policy/target-code.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+) create mode 100644 src/policy/target-code.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index aeb1cdf..712c3af 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -20,6 +20,7 @@ - [When to `#[inline]`](./policy/inline.md) - [Doc alias policy](./policy/doc-alias.md) - [Safety comments policy](./policy/safety-comments.md) + - [Reviewing target-specific code](./policy/target-code.md) - [Tricky situations]() - [Drop and `#[may_dangle]`](./tricky/may-dangle.md) diff --git a/src/policy/target-code.md b/src/policy/target-code.md new file mode 100644 index 0000000..12fcd35 --- /dev/null +++ b/src/policy/target-code.md @@ -0,0 +1,25 @@ +# Reviewing target-specific code + +When reviewing target-specific code, depending on the [tier] of the target in +question, different level of scrutiny is expected from reviewers. + +For tier 1 targets, the reviewer should perform a full review of the code. +Essentially treat the code as *not* platform specific. + +For tier 2 and tier 3 targets, the reviewer should confirm that the code: + +* Only affects 1 or more of such targets (i.e., is truly target-specific) +* Does not introduce new licensing hazards (e.g., license headers or similar) +* Is either proposed by a target maintainer[^1] or has pinged and received +1s + from at least one target maintainer. Where no maintainer is present, look for + whether the author is reputable and/or affiliated with the target in some way + (e.g., authored original code, works for a company maintaining the target, etc.). + +Note that this review does *not* include checking for correctness or for code +quality. We lack the review bandwidth or expertise to perform detailed reviews +of tier 2 and tier 3 targets. + +[^1]: Target maintainers are listed for most targets in the [platform support] documentation. + +[tier]: https://doc.rust-lang.org/nightly/rustc/platform-support.html +[platform support]: https://doc.rust-lang.org/nightly/rustc/platform-support.html From a88166a9f54962a1429f1ba776e373d15ca8afec Mon Sep 17 00:00:00 2001 From: Ben Kimock Date: Fri, 9 Feb 2024 19:48:29 -0500 Subject: [PATCH 76/79] Add a page for unsafe precondition checks --- src/policy/unsafe-preconditions.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 src/policy/unsafe-preconditions.md diff --git a/src/policy/unsafe-preconditions.md b/src/policy/unsafe-preconditions.md new file mode 100644 index 0000000..dcbb365 --- /dev/null +++ b/src/policy/unsafe-preconditions.md @@ -0,0 +1,9 @@ +# Runtime checks for preconditions of `unsafe fn` + +When possible, a debug assertion for the preconditions of an `unsafe fn` should be added inside the body of said function, before the implementation exploits the precondition. + +The compiler supports two kinds of debug assertions. Those that branch on `cfg(debug_assertions)` such as `debug_assert!` or `debug_assert_nounwind!` will be compiled out of the standard library distributed by rustup. Such checks are still valuable to add because they can be used by external tools like [cargo-careful](https://crates.io/crates/cargo-careful) or [cargo-fuzz](https://crates.io/crates/cargo-fuzz), users of `-Zbuild-std` or just our own CI (because it enables both optimizations and debug assertions). + +When it does not impose a significant compile-time burden, debug assertions should be implemented by branching on `intrinsics::debug_assertions()`. That intrinsic is only lowered after monomorphization, so calls to that intrinsic which appear in public and `#[inline]` or generic functions will be enabled by users in builds that enable debug assertions. We have a macro for automating the best use pattern for this intrinsic, `intrinsics::assert_unsafe_precondition!`. This macro shifts all the actual checking logic into a monomorphic and `#[inline(never)]` function, which ensures that the check and error reporting logic is compiled once instead of again and again for each monomorphization that uses the check. + +`assert_unsafe_precondition!` also uses `const_eval_select` internally so that it is only enabled at runtime. When you need a runtime-only check (for example, if your precondition is about pointer alignment) but the compile-time overhead of the branch and call that it expands to is too significant, it is fine to write `#[cfg(debug_assertions)] assert_unsafe_precondition!`. From 34d39de1cdff559b93ea9118e4b4584fd52e9213 Mon Sep 17 00:00:00 2001 From: daddinuz Date: Sat, 28 Sep 2024 09:28:10 +0200 Subject: [PATCH 77/79] fix typo in feature-lifecycle.md --- src/development/feature-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/development/feature-lifecycle.md b/src/development/feature-lifecycle.md index ce51bce..dc015e5 100644 --- a/src/development/feature-lifecycle.md +++ b/src/development/feature-lifecycle.md @@ -35,7 +35,7 @@ Keep the following points in mind during the discussion: - An overly specific API does not cover all common use cases, and may require further API changes in the future to accomodate these use cases. - An alternative that should *always* be considered is simply adding this feature via a third party crate. This is even possible when adding new methods to standard library types by using extension traits. - In the case of "convenience" functions which are simply shorthands for something that is already possible with existing APIs, the cost of extending the standard library surface should be weighed against the ergonomic impact of the new functions. - - For example, too many convenience methods on a type makes nagivating the documentation more difficult. + - For example, too many convenience methods on a type makes navigating the documentation more difficult. - Additionally, consider whether this method is likely to be deprecated in the future if a language-level improvement makes it unnecessary. The library team itself is not directly involved in this discussion, but individual members may comment to provide feedback. If significant changes have occurred since the ACP, another one may be proposed at this point to have the design validated by the library API team. From 5b1f52743f8edd00636582ae3ebf9dd61b51d77b Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Fri, 10 Jan 2025 16:56:13 +0200 Subject: [PATCH 78/79] Explain why the standard library uses extension traits rather than `cfg` --- src/SUMMARY.md | 1 + src/policy/extension-traits.md | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+) create mode 100644 src/policy/extension-traits.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 712c3af..23191dd 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -21,6 +21,7 @@ - [Doc alias policy](./policy/doc-alias.md) - [Safety comments policy](./policy/safety-comments.md) - [Reviewing target-specific code](./policy/target-code.md) + - [Why the standard library uses extension traits](./policy/extension-traits.md) - [Tricky situations]() - [Drop and `#[may_dangle]`](./tricky/may-dangle.md) diff --git a/src/policy/extension-traits.md b/src/policy/extension-traits.md new file mode 100644 index 0000000..b69f28c --- /dev/null +++ b/src/policy/extension-traits.md @@ -0,0 +1,22 @@ +# Why the standard library uses extension traits (and not `cfg`-guarded items) + +A common pattern in the standard library is to put target-specific methods into +extension traits, rather than providing them as `cfg`-guarded methods directly +on objects themselves. For example, the many extension traits in +[`std::os::unix::prelude`](https://doc.rust-lang.org/std/os/unix/prelude/index.html) +provide UNIX-specific methods on standard types. + +The standard library could, instead, provide these methods directly on the +standard types, guarded by `#[cfg(unix)]`. However, it does not do so, and PRs +adding `cfg`-guarded methods are often rejected. + +Providing these methods via extension traits forces code to explicitly use +those extension traits in order to access the methods. This, effectively, +requires code to declare whether it depends on target-specific functionality, +either because the code is target-specific, or because it has appropriately +`cfg`-guarded code for different targets. Without these extension traits, code +could more easily use target-specific functionality "accidentally". + +This policy may change in the future if Rust develops better mechanisms for +helping code explicitly declare its portability, or lack of portability, before +accessing target-specific functionality. From 3158d0e090a3fd90ece1a9e6486bdf79d2a389d6 Mon Sep 17 00:00:00 2001 From: John M Butler IV <66403651+john-butler-iv@users.noreply.github.com> Date: Tue, 15 Apr 2025 20:29:29 -0500 Subject: [PATCH 79/79] Fix typo --- src/development/stabilization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/development/stabilization.md b/src/development/stabilization.md index 5adf6c3..e5fcb01 100644 --- a/src/development/stabilization.md +++ b/src/development/stabilization.md @@ -15,7 +15,7 @@ If you're unsure if a feature is ready for stabilization the first step should b ## Stabilization Report -Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports are not mandatory but they are heavily encouraged, and may be mandated by library API team members if they feel it necessary. The purpose of stabilization reports is to help reviewers more quickly make decisions and to simplify the process of documenting stabilized APIs in release notes. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report. +Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports are not mandatory but they are heavily encouraged, and may be mandated by library API team members if they feel it necessary. The purpose of stabilization reports is to help reviewers more quickly make decisions and to simplify the process of documenting stabilized APIs in release notes. Stabilization reports consist of three primary sections, an implementation history, an API summary, and an experience report. The **Implementation History** section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved.