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.

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.

A tour of the standard library

Status: Stub

The standard library codebase lives in the 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.

The Library Team

The Rust standard library and the official rust-lang crates are the responsibility of the Library Team. The Library team makes sure the libraries are maintained, PRs get reviewed, and issues get handled in time, although that does not mean the team members are doing all the work themselves. Many team members and other contributors are involved in this work, and the team's main task is to guide and enable that work.

The Library API Team

A very critical aspect of maintaining and evolving the standard library is its stability. Unlike other crates, we can not release a new major version once in a while for backwards incompatible changes. Every version of the standard library is semver-compatible with all previous versions since Rust 1.0.

This means that we have to be very careful with additions and changes to the public interface. We can deprecate things if necessary, but removing items or changing signatures is almost never an option. As a result, we are very careful with stabilizing additions to the standard library. Once something is stable, we're basically stuck with it forever.

To guard the stability and prevent us from adding things we'll regret later, we have a team that specifically focuses on the public API. Every RFC and stabilization of a library addition/change goes through a FCP process in which the members of the Library API Team are asked to sign off on the change.

The members of this team are not necessarily familiar with the implementation details of the standard library, but are experienced with API design and understand the details of breaking changes and how they are avoided.

The Library Contributors

In addition to the two teams above, we also have a the Library Contributors, which is a somewhat more loosely defined team consisting of those who regularly contribute or review changes to the standard libraries.

Many of these contributors have a specific area of expertise, for example certain data structures or a specific operating system.

Team Membership

The Library Team will privately discuss potential new members for itself and Library Contributors, and extend an invitation after all members and the moderation team is on board with the potential addition.

See Membership 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. See Reviewing for details.

high-five rotation

Some of the members of the team are part of the 'high-five rotation'; the list from which the high-five bot picks reviewers to assign new PRs to.

Being a member of one of the teams does not come with the expectation to be on this list. However, members of this list should be on at least one of the three library teams. See Reviewing for details.

Meetings

Currently, both the Library Team and the Library API Team have a weekly hour-long meeting. Both meetings are open to non-members by default, although some might be (partially) private when agenda topics require that.

The meetings are held as video calls through Jitsi, but everyone is welcome to join without video or even audio. If you want to participate in meeting discussions through text, you can do so through Jitsi's chat function.

Meetings and their agendas are announced in the #t-libs/meetings channel on Zulip.

Agendas are generated by the fully-automatic-rust-libs-team-triage-meeting-agenda-generator, which will include all relevant issues and PRs, such as those tagged with I-nominated or S-waiting-on-team.

If you have any specific topics you'd like to have discussed in a meeting, feel free to open an issue on the libs-team repository and mark it as I-nominated and T-libs or T-libs-api. Or just leave a message in the Zulip channel.

All the meetings, including those of the library working groups, can be found on our Google Calendar:

ICS link

Membership

Library Contributors

Membership to Library Contributors can be offered by the Library Team once a regular contributor has made a number of significant contributions over some period of time, and has shown to have a good judgement on what changes are acceptable.

The Library Team and Library API Team

The Library Team and Library API Team pick their own members, although it's expected that new members come from the Library Contributors or another Rust team, and have already been involved in relevant library work.

The process

In all cases, the process of adding a new members goes as follows:

A member of the Library (API) Team proposes the addition of a contributor on our private Zulip channel. This proposal includes:
- A short description of what this person has been working on; how they have been contributing.
- A few specific examples of cases where this person clearly communicated their ideas.
- A few specific examples that show this person understands what are and what aren't acceptable changes.
  Someone who makes significant contributions but usually needs to make large adjustments to their PRs might be a wonderful external contributor, but might not yet be a good match for membership with review permissions expecting to judge other contributions.
Every single team member is asked for their input. No team member must have any objections.
- Objections are ideally shared with the entire team, but may also be shared privately with the team lead or the moderation team.
- Objections ideally include examples showing behavior not in line with the expectations described under step 1 (or the code of conduct).
The team lead reaches out to the moderation team to ask if they are aware of any objections.
Only once the team members and the moderation team agree, the new contributor is invited to join.
If the new contributor agrees too, a PR is sent to the team repository to add them.
A blog post is published in the Internals Blog with a short introduction of the new contributor. The contents of this post can be based on some of the points brought up in the email from step 1. The contents are first checked with the new contributor before it is published.

Reviewing

Every member of the Library Team, Library API Team, and Library Contributors has 'r+ rights'. That is, the ability to approve a PR and instruct @bors to test and merge it into Rust nightly.

If you decide to review a PR, thank you! But please keep in mind:

You are always welcome to review any PR, regardless of who it is assigned to. However, do not approve PRs unless:
- You are confident that nobody else wants to review it first. If you think someone else on the team would be a better person to review it, feel free to reassign it to them.
- You are confident in that part of the code.
- You are confident it will not cause any breakage or regress performance.
- It does not change the public API, including any stable promises we make in documentation, unless there's a finished FCP for the change.
  - For unstable API changes/additions, it can be acceptable to skip the RFC process if the design is small and the change is uncontroversial. Make sure to involve @rust-lang/libs-api on such changes.
Always be polite when reviewing: you are a representative of the Rust project, so it is expected that you will go above and beyond when it comes to the Code of Conduct.

High-five rotation

Some of the members of the team are part of the 'high-five rotation'; the list from which the high-five bot picks reviewers to assign new PRs to.

Being a member of one of the teams does not come with the expectation to be on this list. However, members of this list should be on at least one of the three library teams.

If the bot assigns you a PR for which you do not have the time or expertise to review it, feel free to reassign it to someone else. To assign it to another random person picked from the high-five rotation, use r? 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.

Building and Debugging the library crates

Most of the instructions from the rustc-dev-guide also apply to the standard library since it is built with the same build system, so it is recommended to read it first.

Println-debugging alloc and core

Since logging and IO APIs are not available in alloc and core advice meant for the rest of the compiler is not applicable here.

Instead one can either extract the code that should be tested to a normal crate and add debugging statements there or on POSIX systems one can use the following hack:


#![allow(unused)]
fn main() {
extern "C" {
    fn dprintf(fd: i32, s: *const u8, ...);
}

macro_rules! dbg_printf {
    ($s:expr) => {
        unsafe { dprintf(2, "%s\0".as_ptr(), $s as *const u8); }
    }
}

fn function_to_debug() {
    let dbg_str = format!("debug: {}\n\0", "hello world");
    dbg_printf!(dbg_str.as_bytes().as_ptr());
}
}

Then one can run a test which exercises the code to debug and show the error output via

./x.py test library/alloc --test-args <test_name> --test-args --no-capture

The feature lifecycle

Status: Stub

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.

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.

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 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.

Stabilizing features

Status: Current
Last Updated: 2022-05-27

Feature stabilization involves adding #[stable] attributes. They may be introduced alongside new trait impls or replace existing #[unstable] attributes.

Stabilization goes through the Libs FCP (Final Comment Period) process, which typically occurs on the tracking issue for the feature.

When is an FCP appropriate?

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 directly to request assistance.

Stabilization Report

Once a feature is ready for stabilization the first step of the FCP process is writing a stabilization report. Stabilization reports are not mandatory but they are heavily encouraged, and may be mandated by library API team members if they feel it necessary. The purpose of stabilization reports is to help reviewers more quickly make decisions and to simplify the process of documenting stabilized APIs in release notes. Stabilization reports consist of three primary sections, a implementation history, an API summary, and an experience report.

The Implementation History section should summarize the initial discussion during the implementation PR, every change that has been made to the feature since the initial implementation, all issues that were raised during the lifetime of the feature, and how they were resolved.

The API Summary section should include a precise description of what APIs are being introduced to the standard libraries. This can often be a simple link back to the top level comment if it's up to date, but in 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 that can be used to generate these API summaries in some cases. Note the current implementation of this tool is fragile and does not work in all cases. We hope to have a more permanent version of this tool in the future that is built ontop of either rustdoc or rustc's own APIs.

The Experience Report section should include concrete usecases of users who have wanted to use the feature and who have tested that it works for their needs. The experience report should include a brief summary of the experience of using that feature. Ideally this would include links to commits or branches where the feature was integrated with their project, but this is not a requirement. Alternatively, users can provide usage examples of crates that export an identical API to the one being stabilized.

You can see an example of a stabilization report in #88581.

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.

This will save you from opening a stabilization PR and having it need regular rebasing while the FCP process runs its course.

Partial Stabilizations

When you only wish to stabilize a subset of an existing feature you should skip creating a new tracking issue and instead create a partial stabilization PR for the subset of the feature being stabilized.

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 directly to request assistance.

You can see an example of partially stabilizing a feature with tracking issue #71146 and partial stabilization PR #94640.

When there's `const` involved

Const functions can be stabilized in a PR that replaces #[rustc_const_unstable] attributes with #[rustc_const_stable] ones. The Constant Evaluation WG should be pinged for input on whether or not the const-ness is something we want to commit to. If it is an intrinsic being exposed that is const-stabilized then @rust-lang/lang should also be included in the FCP.

Check whether the function internally depends on other unstable const functions through #[allow_internal_unstable] attributes and consider how the function could be implemented if its internally unstable calls were removed. See the Stability attributes page for more details on #[allow_internal_unstable].

Where unsafe and const is involved, e.g., for operations which are "unconst", that the const safety argument for the usage also be documented. That is, a const fn has additional determinism (e.g. run-time/compile-time results must correspond and the function's output only depends on its inputs...) restrictions that must be preserved, and those should be argued when unsafe is used.

Stabilization PR for Library Features

Once we have decided to stabilize a feature, we need to have a PR that actually makes that stabilization happen. These kinds of PRs are a great way to get involved in Rust, as they're typically small -- just updating attributes.

Here is a general guide to how to stabilize a feature -- every feature is different, of course, so some features may require steps beyond what this guide talks about.

Update the stability attributes on the items

Library items are marked unstable via the #[unstable] attribute, like this:

#[unstable(feature = "total_cmp", issue = "72599")]
pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { ... }

You'll need to change that to a #[stable] attribute with a version:

#[stable(feature = "total_cmp", since = "1.61.0")]

Note that, the version number is updated to be the version number of the stable release where this feature will appear. This can be found by consulting src/version on the current master branch of rust-lang/rust.

Remove feature gates from doctests

All the doctests on the items being stabilized will be enabling the unstable feature, so now that it's stable those attributes are no longer needed and should be removed.

 /// # Examples
 ///
 /// ```
-/// #![feature(total_cmp)]
-///
 /// assert_eq!(0.0_f32.total_cmp(&-0.0), std::cmp::Ordering::Greater);
 /// ```

The most obvious place to find these is on the item itself, but it's worth searching the whole library. Often you'll find other unstable methods that were also using it in their tests.

Remove feature gates from the compiler

The compiler builds with nightly features allowed, so you may find uses of the feature there as well. These also need to be removed.

 #![feature(once_cell)]
 #![feature(never_type)]
-#![feature(total_cmp)]
 #![feature(trusted_step)]
 #![feature(try_blocks)]

Stabilization PR Checklist

To stabilize a feature, follow these steps:

Create a stabiliation report in the tracking issue for the feature being stabilized.
(Optional) For partial stabilizations, create a new partial stabilization PR for the subset of the issue being stabilized.
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).
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 on the master branch of rust-lang/rust.
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.
If applicable, change #[rustc_const_unstable(...)] to #[rustc_const_stable(since = "version")].
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".

You can see an example of stabilizing a feature with tracking issue #81656 with FCP and the associated implementation PR #84642.

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 #[rustc_deprecated] attribute. Deprecating need to go through a Libs FCP, just like stabilizations do.

To try reduce noise in the docs from deprecated items, they should be moved to the bottom of the module or impl block so they're rendered at the bottom of the docs page. The docs should then be cut down to focus on why the item is deprecated rather than how you might use it.

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!

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.

Standard library developers Guide