Stabilize #![feature(staged_api)]

[GuillaumeGomez]

The idea behind it is to allow users to mark items as not yet stable for their crates, allowing them to change it without requiring to make a new major release. It'll will require a few changes though. Currently, the unstable attribute looks like this:

#[unstable(feature = "some_feature", reason = "some reason", issue = "123")]

So here is what I suggest:

• Enforce feature only for rustc.
• Force issue to have a full URL outside of rustc (maybe even inside?).
• Keep reason, I think it's fine to have a reason.

Once this done, rustdoc would also need to make some updates:

• If unstable is used on a module, all its children (and children of its children recursively) should say that a parent is unstable and therefore this item is unstable too (which is message like a parent of _child_ is unstable, therefore _child_ is unstable too). This message should be put at the top of the item page and not repeated on any of the element of the page to prevent adding unnecessary noise.
• If both a parent and the item are unstable, only display the message of the item.
• If two parents are unstable, only print message of the closest one.

What do you think?

cc @rust-lang/compiler @rust-lang/rustdoc @RDambrosio016

[Mark-Simulacrum]

This seems like it would not really be a T-compiler/T-rustdoc issue, but rather a proposal to stabilize a subset of the staged_api feature. I think this would be significant enough that we'd want an RFC, likely T-lang, and probably a project group to focus on identifying the problems to solve / solution space before trying to propose a specific solution.

[RDambrosio016]

It may be very helpful to allow users to specify a custom message for the text shown in the rustdoc docs instead of always using "this item/struct is unstable and subject to change"

[bjorn3]

What about also requiring #![feature] for these, but simply allowing it to be used on stable?

[jyn514]

I think discussion about this should be a pre-RFC on internals or a full-blown RFC, both of which have better tools for interleaved conversations. Probably a pre-RFC since it sounds like staged_api shouldn't be stabilized as-is.

[poliorcetics]

That sounds like a really nice feature. I agree it needs some design though.

[Cldfire]

It would be very hepful for this attribute to support linking to the issue specified (inspired by the Rust Search Extension):

Image

This would probably require a way to globally specify a root issue URL for a given crate.

EDIT: ah, the original issue description mentions Force issue to have a full URL outside of rustc (maybe even inside?)., so consider this comment added context to that 😄

[Nemo157]

Pre-emptively, I would like it if the URL is not required to be an http(s) one. As an example of current non-http issue URLs there is Apple's radr:// scheme, and I think there is a decent chance of decentralized/federated/p2p project management solutions using custom schemes becoming popular enough within the next few years.

[Ezrashaw]

Hmm, I wonder if this shouldn't use the existing #[stable(...)] and #[unstable(...)], perhaps a new feature should be implemented. The behavior intended seems subtly different from the current use of those attributes.

On another note, (I assume you mean stdlib as well as rustc)

• Enforce feature only for rustc.

• Force issue to have a full URL outside of rustc (maybe even inside?).

• Keep reason, I think it's fine to have a reason.

How do you intend to determine if the currently compiling code is stdlib or rustc? Currently this is the way to know, and (AFAIK) there is no other good replacement.

[jhpratt]

Huh, apparently I subscribed to this issue at some point, yet I don't recall ever having seen it.

To put it bluntly: I strongly oppose stabilizing #![feature(staged_api)] in its current form. It is a massive change that has not gone through the RFC process. I hope to have some design work laid out in the near-ish future, with the intent being that said work lays the basis for a formal RFC. I already have it in my head; I need to write it down.

[Ezrashaw]

Yes, there was some discussion on discord about this as well. Everyone recognizes the need for a RFC, this is a kind of pre-RFC (I don't think OP realized that an RFC was needed).

[GuillaumeGomez]

No, even at the time it was something I was targetting. I just wasn't sure if the discussion about it should happen on the RFC or on the issue first.