Stabilizing APIs in the standard library

[alexcrichton]

Each release of Rust we’ve typically got at least a few new APIs that are being stabilized in the standard library. This has historically been done by the libs team but is also a great opportunity wanting to help out! I’ll detail the process here and see if we can help start bringing in some new contributors.

All APIs in the standard library start their life marked as #[unstable] and tagged with a tracking issue. For example TcpStream::connect_timeout is unstable right now and points to #43079 as a tracking issue. Notably you’ll also find the T-libs and B-unstable tags on all tracking issues for unstable APIs in the standard library.

Next up in the lifecycle of an unstable API a member of the libs team will propose stabilization and once all libs members have checked their checkboxes the issue is tagged with final-comment-period meaning it’s ready for stabilization. As a side note, anyone can ask for a libs member to propose stabilization!

Next up comes the fun part. For example right now we have a few issues that are all in final-comment-period, which you can typically see through this GitHub query. The second an issue goes into FCP it’s ready for a “stabilization PR” which tends to look like this, namely:

• The #[unstable] tag is changed to #[stable] with an appropriate version listed
• The PR/commit message mentions Closes #xxx to close out the tracking issue once it’s landed
• Various test code and crates using the feature have their #![feature] directives deleted

And that’s it! Often times we don’t have a PR-per-issue-in-final-comment-period like the mem::discriminant PR listed above, but instead there’s a batch PR for all current final-comment-period issues with a commit-per-issue. Either way is fine!

Now timing-wise ideally what would happen is that as soon as all issues enter final-comment-period we’d get a PR to stabilize the issue and we’d land it via bors. Typically that doesn’t happen, so we instead shoot for a PR just before the end of a cycle to stabilize all current final-comment-period issues (a batch PR). Typically though even that doesn’t happen so we often just after the beta branches make a batch PR to the master branch and then backport it to the beta branch.

This is where you can help! For the upcoming 1.21 release we haven’t yet landed the batch of stabilizations that we’ll want for the release. The mem::discriminant PR is an example of one that we’ll be backporting (as we should have landed it before beta branched), but there’s a few more final-comment-period issues! If you’re interested in helping out here please let us know! A member of the libs team will try to post to this thread when a cycle is just around the corner as a reminder to go through final-comment-period issues and stabilize them as well.

[aturon]

This writeup, once we’re happy with it, should go on the forge.

[dtolnay]

I’ve never done this before so I would like to give this a shot for this cycle. Will get to it in the next day or two if nobody else has a PR by then.

[djc]

How does the process for stabilization proposals work? From superficially running into APIs I wanted every now and again, it feels like there are a lot of unstable APIs (one recent example) and not a lot of bandwidth to go around to get stuff stabilized. Is someone monitoring the trend on the size of the queue for this?

[alexcrichton]

An excellent question! Right now it’s relatively ad-hoc and done in an on-demand basis. Many unstable APIs today are unlikely to stabilize as-is. We’ve been trying to think of better ways to traige this list, but here’s all unstable library APIs

[dtolnay]

@budziq ended up doing all the remaining ones for this cycle. Much appreciated!

• Stabilize TcpStream::connect_timeout
• Stabilize Vec::splice
• Stabilize mem::needs_drop
• Stabilize atomic::compiler_fence
• Stabilize Ord::min and max
• Stabilize Iterator::for_each

If anyone wants these backported, we’ll adjust the “since” version similar to what #44552 did for mem::discriminant.

[budziq]

@dtolnay

@budziq ended up doing all the remaining ones for this cycle.

I might have gotten a tad overzealous . I think there is still one FPC open (DNS in std::net - #27705). If it is not too contentious to stabilize, someone else might give it a try. It's great way to get your feet wet with rust-lang repo!

[alexcrichton]

@budziq oh actually that was an FCP-to-close which is actually slightly different, that means that we apply the #[rustc_deprecated] attribute instead of the #[stable] attribute (leaving it as an unstable API).

[djc]

@alexcrichton

An excellent question! Right now it’s relatively ad-hoc and done in an on-demand basis. Many unstable APIs today are unlikely to stabilize as-is. We’ve been trying to think of better ways to traige this list, but here’s all unstable library APIs

I pulled data from the GitHub API to explore this a little bit. The number of T-libs + B-unstable issues is nicely flat over time, but the median age of the open issues is increasing. Maybe try to pick up some old ones next time? Or close them, if they're sitting in the queue because no one wants them?

Data + chart here: Rust libs tracking issues history - Google Drive

I can push the Python code + cached JSON data to GitHub if people are interested.