From 83c8e284b63ceceb4e427f32829bef2cddf90287 Mon Sep 17 00:00:00 2001 From: Matthew Jasper Date: Mon, 4 Oct 2021 21:19:25 +0100 Subject: [PATCH 01/30] 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 a0a5dc714d02eca656fc89dcbecd1e4e9836ecf0 Mon Sep 17 00:00:00 2001 From: Jane Lusby Date: Tue, 7 Jun 2022 13:03:05 -0700 Subject: [PATCH 02/30] 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 03/30] 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 04/30] 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 05/30] 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 06/30] 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 07/30] 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 08/30] 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 09/30] 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 10/30] 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 11/30] 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 12/30] 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 13/30] 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 14/30] 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 15/30] 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 16/30] - 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 17/30] 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 18/30] 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 19/30] 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 20/30] 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 21/30] 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/%7Bpath%7D" + +[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 22/30] 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 23/30] 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 24/30] 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 25/30] 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 26/30] 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 27/30] 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 28/30] 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 29/30] 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 30/30] 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.