Document how to stabilize a library feature (#1036)

* Move 'force-unstable-if-unmarked' to the bootstrapping chapter

* Document how to stabilize a library feature

Note that features can't be stabilized until they go through FCP and
that FCP happens on the tracking issue, not the PR.

* Fix wrong glob

By default `**` behaves the same as two `*` side by side, i.e. it only
globs file paths, not directories. `shopt -s globstar` needs to be set
for it to mean a directory. I didn't notice this before now because
`globstar` is set by default in interactive mode, but not otherwise.

Author: jyn514

ci/check_line_lengths.sh

@@ -10,6 +10,7 @@ if [ "$MAX_LINE_LENGTH" == "" ]; then
 fi
 
 if [ "$1" == "" ]; then
+  shopt -s globstar
   files=( src/**/*.md )
 else
   files=( "$@" )

src/building/bootstrapping.md

@@ -313,12 +313,42 @@ of the public API of the standard library, but are used to implement it.
 `rustlib` is part of the search path for linkers, but `lib` will never be part
 of the search path.
 
+#### -Z force-unstable-if-unmarked
+
 Since `rustlib` is part of the search path, it means we have to be careful
 about which crates are included in it. In particular, all crates except for
 the standard library are built with the flag `-Z force-unstable-if-unmarked`,
 which means that you have to use `#![feature(rustc_private)]` in order to
 load it (as opposed to the standard library, which is always available).
 
+The `-Z force-unstable-if-unmarked` flag has a variety of purposes to help
+enforce that the correct crates are marked as unstable. It was introduced
+primarily to allow rustc and the standard library to link to arbitrary crates
+on crates.io which do not themselves use `staged_api`. `rustc` also relies on
+this flag to mark all of its crates as unstable with the `rustc_private`
+feature so that each crate does not need to be carefully marked with
+`unstable`.
+
+This flag is automatically applied to all of `rustc` and the standard library
+by the bootstrap scripts. This is needed because the compiler and all of its
+dependencies are shipped in the sysroot to all users.
+
+This flag has the following effects:
+
+- Marks the crate as "unstable" with the `rustc_private` feature if it is not
+  itself marked as stable or unstable.
+- Allows these crates to access other forced-unstable crates without any need
+  for attributes. Normally a crate would need a `#![feature(rustc_private)]`
+  attribute to use other unstable crates. However, that would make it
+  impossible for a crate from crates.io to access its own dependencies since
+  that crate won't have a `feature(rustc_private)` attribute, but *everything*
+  is compiled with `-Z force-unstable-if-unmarked`.
+
+Code which does not use `-Z force-unstable-if-unmarked` should include the
+`#![feature(rustc_private)]` crate attribute to access these force-unstable
+crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or
+`clippy`.
+
 You can find more discussion about sysroots in:
 - The [rustdoc PR] explaining why it uses `extern crate` for dependencies loaded from sysroot
 - [Discussions about sysroot on Zulip](https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp/topic/deps.20in.20sysroot/)

src/stability.md

@@ -44,12 +44,8 @@ prevents breaking dependencies by leveraging Cargo's lint capping.
 [rustc bug]: https://github.com/rust-lang/rust/issues/15702
 
 ## stable
-
 The `#[stable(feature = "foo", "since = "1.420.69")]` attribute explicitly
-marks an item as stabilized. To do this, follow the instructions in
-[Stabilizing Features](./stabilization_guide.md).
-
-Note that stable functions may use unstable things in their body.
+marks an item as stabilized. Note that stable functions may use unstable things in their body.
 
 ## rustc_const_unstable
 
@@ -72,6 +68,24 @@ even on an `unstable` function, if that function is called from another
 Furthermore this attribute is needed to mark an intrinsic as callable from
 `rustc_const_stable` functions.
 
+## Stabilizing a library feature
+
+To stabilize a feature, follow these steps:
+
+0. Ask a **@T-libs** member to start an FCP on the tracking issue and wait for
+   the FCP to complete (with `disposition-merge`).
+1. Change `#[unstable(...)]` to `#[stable(since = "version")]`.
+   `version` should be the *current nightly*, i.e. stable+2. You can see which version is
+   the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions).
+2. 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.
+3. If applicable, change `#[rustc_const_unstable(...)]` to
+   `#[rustc_const_stable(since = "version")]`.
+4. Open a PR against `rust-lang/rust`.
+   - Add the appropriate labels: `@rustbot modify labels: +T-libs`.
+   - Link to the tracking issue and say "Closes #XXXXX".
+
+You can see an example of stabilizing a feature at [#75132](https://github.com/rust-lang/rust/pull/75132).
 
 ## allow_internal_unstable
 
@@ -130,35 +144,4 @@ default `allow`, but most of the standard library raises it to a warning with
 `#![warn(deprecated_in_future)]`.
 
 [`deprecated` attribute]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-deprecated-attribute
-
-## -Z force-unstable-if-unmarked
-
-The `-Z force-unstable-if-unmarked` flag has a variety of purposes to help
-enforce that the correct crates are marked as unstable. It was introduced
-primarily to allow rustc and the standard library to link to arbitrary crates
-on crates.io which do not themselves use `staged_api`. `rustc` also relies on
-this flag to mark all of its crates as unstable with the `rustc_private`
-feature so that each crate does not need to be carefully marked with
-`unstable`.
-
-This flag is automatically applied to all of `rustc` and the standard library
-by the bootstrap scripts. This is needed because the compiler and all of its
-dependencies are shipped in the sysroot to all users.
-
-This flag has the following effects:
-
-- Marks the crate as "unstable" with the `rustc_private` feature if it is not
-  itself marked as stable or unstable.
-- Allows these crates to access other forced-unstable crates without any need
-  for attributes. Normally a crate would need a `#![feature(rustc_private)]`
-  attribute to use other unstable crates. However, that would make it
-  impossible for a crate from crates.io to access its own dependencies since
-  that crate won't have a `feature(rustc_private)` attribute, but *everything*
-  is compiled with `-Z force-unstable-if-unmarked`.
-
-Code which does not use `-Z force-unstable-if-unmarked` should include the
-`#![feature(rustc_private)]` crate attribute to access these force-unstable
-crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or
-`clippy`.
-
 [blog]: https://www.ralfj.de/blog/2018/07/19/const.html

src/stabilization_guide.md

@@ -1,5 +1,10 @@
 # Request for stabilization
 
+**NOTE**: this page is about stabilizing language features.
+For stabilizing *library* features, see [Stabilizing a library feature].
+
+[Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature
+
 Once an unstable feature has been well-tested with no outstanding
 concern, anyone may push for its stabilization. It involves the
 following steps: