What is the stabilization process?

Question

What is the stabilization process? Reading the release notes I see a lot of different standard library APIs and even language features (e.g. underscore lifetimes). How does an API become stable?

Answer 1

Stabilization is the way that new features are added to Rust. Unlike many languages, where when stuff is added, it goes in the next release, Rust has a multi-stage process so that we can try out features before they're slated to be included in stable Rust.

Small features, especially new library APIs, can be added by just sending in a pull request. Larger features go through the RFC process, so that there can be some consensus around the design before they're implemented. If an RFC is accepted, an implementation can be sent in via PR. Whenever a new feature is added, it goes behind a "feature gate", that is, a special attribute, #![feature], that lets you opt into giving that feature a try.

Every (okay sometimes not every but almost every) night, a nightly build of Rust is made. Nightly builds are used for testing, and so, you can opt into new, unstable features using the #![feature] attribute. Users then give these features a whirl, report bugs, and comment on how the API or feature is used in the real world.

Every six weeks, a nightly is turned into a "beta" release. Betas are like release candidates, and so they don't allow you to use #![feature], and so, don't let you use experimental features. After six weeks, a new nightly becomes beta, and the beta release becomes a new "stable" release. This is what most people mean when they talk about Rust, and what most Rust users use. Stable Rust also doesn't let you use #![feature], as those features aren't stable.

Anyway, after a time (that's at least one whole release cycle), if a feature is good, the team discusses if it should be made stable. If they decide yes, then the #![feature] requirement is removed, and the feature will "ride the trains" to an eventual stable release. If they decide no, it will be deprecated and eventually removed.

Answer 2

Rust favors an agile approach to introducing features and APIs, in order to iterate on them based on feedback¹.

However, iterating over the design of features or APIs is at odds with Rust strong commitment to backward compatibility (aka stability). Therefore, the Stabilization Process was designed to resolve this apparent conundrum:

• any non-trivial feature or API addition is first unstable, and hidden behind a feature gate,
• to use such a feature, the user must opt-in using #![feature] in their crate,
• it is only possible to opt-in on the nightly release channel, and impossible on the beta or stable release channels.

This way, enthusiasts can use nightly to experiment with the feature, and provide feedback to polish it, while any other user can use any feature available and be confident they will not accidentally use an unstable one.

Once a feature is judged ready, the final step is to have the team in charge approve it; the feature gate is then removed and the feature becomes available on all channels (though it takes some time to propagate from nightly to stable, of course).

¹ A famous example of specification failure was the "export template" functionality of C++98; it was only ever implemented in the EDG front-end and this sole feature took over a year. Since then, the C++ committee generally requires prototype implementations.