stable/unstable/nightly-only features

[ehuss]

Some packages have features that they intend to be "unstable" in that they enable functionality that may change over time, or may even be removed. Closely related to this are features that enable nightly-only functionality (see nightly-only features). I'm not sure if these two are distinct enough to consider separately, though they seem pretty similar to me.

Currently the documentation just recommends clearly documenting which features are unstable. However, that does not provide very good assurances that users know what they are opting into.

I don't know what would be a good way to make it clear that one is opting into an unstable feature. Another consideration is to possibly deny the use of unstable features.

Possible syntax may look like:

[features.foobar]
unstable = true

One thing to consider is the possible confusion of the term "unstable features" with Cargo's own Unstable Features. I'm not sure what terminology would be best here.

I'm opening this issue to track this feature request, but this isn't something we will likely pursue in the near term. This will require an RFC to explore the design in more detail.

See also:

• private/hidden features: private/hidden features #10882
• deprecated features: Feature Request: A way to deprecate features #7130
• feature descriptions: Allow adding a description for features #4956

[Pr0methean]

I'd suggest that the definition of such a feature also be able to include a rust-version that's either nightly or a later stable version than the crate's rust-version, so that unstable features can use newer/unstable compiler features and the source of any incompatibility will be clear to the user.

[epage]

Some packages have features that they intend to be "unstable" in that they enable functionality that may change over time, or may even be removed. Closely related to this are features that enable nightly-only functionality (see nightly-only features). I'm not sure if these two are distinct enough to consider separately, though they seem pretty similar to me.

Potentially tying in rust-version to nightly features I think highlights a potential distinctive need between nightly and unstable features.

In rust-lang/rfcs#3416, my proposal for unstable is that its viral (can only be used by other unstable features) but not much other special functionality.

One idea for how we could act on unstable if we move forward with it in this RFC:

• unstable features may only be required by other unstable features or by the command-line

  • Since unstable features are not subject to semver, they may be removed, so any non-existent features that an unstable feature requires produces a warning at most unless the unstable feature is activated, then it errors (no idea how complicated this would be)

• Future possibility: unstable features may also be required when the version requirement is =<x>.<y>.<z>

[epage]

It might also be nice to have any field to mirror the unstable #[stable] attribute