The Life and Death of an API

[huon]

I wonder how crates.io plays into this: i.e. should we consider also explicitly/officially encouraging people to publish things on crates.io to get experience with the API? This clearly applies to the "close the PR" option, but may also be a desirable thing to do with RFCs (and maybe even unstable APIs?) to allow interested parties to try them in their own code, and get guidance from an implementation. (And, if the RFC is eventually rejected, the functionality still exists.)

(Not everything change is going to be sane to do externally, of course, e.g. adding APIs to something complicated like HashMap may require fiddling with its internals.)

@alexcrichton

Having a huge amount of unstable content in the standard library will greatly affect the experience when browsing the documentation, and I do fear that despite the trains there may still be a worry of defacto stability (e.g. if everyone's using nightly b/c it's got all the cool methods).

Complete brainstorming: we could have two levels of unstable, "very unstable" (A) and "normal unstable" (B), which would control how the docs are displayed (e.g. (A) might be collapsed by default, or even hidden?). Changes landing directly via PR would (usually) land as (A), and then there could be weekly/fortnightly sweeps switching (A)'s to (B) (Alternative: just have a queue that changes get added to and do rolling switches). Changes landing via RFC would land as a (A).

This has the downside of being more complicated, but has the upsides of allowing things to land more easily without losing "big picture" considerations too much, and with an easier removal path. The intention would be that users don't see much difference between the two levels of stability (other than differences in the docs).

This would benefit greatly from a nice dashboard as @alexcrichton and @aturon mention. (On that point, I'm also very keen on a dashboard even without some change like this.)

---

For landed APIs, I idly wonder if @nrc's work on DXR could be very useful for the unstable → stable → deprecated steps. If we (somehow) index all of crates.io, we could quickly pull up uses of the functionality in question. This will be most useful if/when crates.io encourages publishing binaries as well as libraries (e.g. when cargo install exists) to get a better cross-section of how things are used.

[glaebhoerl]

@huon My inclination is that unstable APIs shouldn’t show up in the stable docs at all, or only upon explicit request (a “show deprecated and unstable items” link/button). What’s the point of distracting people with and making them wade through APIs which aren’t available to them?

[Uther]

The point is knowing that something is pending.

If the user don’t see the function he need, he might think it is in another module and keep searching, or issue an useless improvement request.

[yigal100]

This reminded me of Debian Releases where the general flow is: unstable -> testing -> stable and an additional “experimental” repository.

This should also be tied to the trains as @Gankra commented:

1. Official releases would continue to contain only stable APIs, as today.
2. The beta channel (i.e. the upcoming next release) would correspond to Debian’s “testing”. This branch would allow access to additional upcoming APIs. Think of this as the “FCP” for an API.
3. The nightly channel would correspond to Debian’s unstable.

ATM, the Rust homepage only contains “nightly” and “stable” channels. where nightly docs correspond to #3 above and stable to #1. The change would be to add an additional “beta” section for docs and add an additional “testing” attribute that would be visible in this section.

• experimental would correspond to out-of-tree experiments to try new ideas and gaining implementation experience for proposed RFCs. People can do that independently in their own repositories.

[aturon]

@huon

I wonder how crates.io plays into this: i.e. should we consider also explicitly/officially encouraging people to publish things on crates.io to get experience with the API? This clearly applies to the "close the PR" option, but may also be a desirable thing to do with RFCs (and maybe even unstable APIs?) to allow interested parties to try them in their own code, and get guidance from an implementation. (And, if the RFC is eventually rejected, the functionality still exists.)

Yes, this is definitely a question we need to consider as part of the policy here.

It's a bit complicated, since it touches on the much harder question of: in the long term, what should live in the standard library, in other rust-lang crates, and in crates.io? I'd like to start a separate thread about that soon, since it's an important strategic question for our library work going forward.

[SimonSapin]

@aturon

in the long term, what should live in the standard library, in other rust-lang crates, and in crates.io? I'd like to start a separate thread about that soon, since it's an important strategic question for our library work going forward.

I’ve started What should go into the standard library?.

[burntsushi]

I think the biggest takeaway from this conversation is that we need better tools. I am also on the conservative side of things and would like to keep the number of unstable items small. Having a dashboard of sorts would be key. Maybe some kind of correspondence between related unstable items and Github issues?

I very much like the heuristic of, “for a small change, submit a PR and get people to comment. If there’s an easy consensus, just merge it.”

[Gankra]

I’ve taken discussion and the last few months’ practical experience into discussion and created a full RFC: https://github.com/rust-lang/rfcs/pull/1213