Currently we have the attribute deprecated
meant for items that are being sunsetted, or are only retained for compatibility. But there's no equivalent attribute for the other end of the life cycle. Many of us are probably painfully aware of the chicken-and-egg problem of trying to get feedback on new features before they're ready, as many users don't want to fully switch to an unstable version just to test something.
The ability to opt in to preview features in otherwise stable releases could lower that threshold. The attribute #[preview]
() could be attached to any item with public visibility and would have the following effects:
- Signal that the item and any contained items are exempted from semantic versioning while in preview
- Cause rustdoc add a warning/de-emphasize/etc the item in docs.
- Trigger a warn-by-default lint (or even deny-by-default?) on any use in a dependent crate.
- Trigger a deny-by-default lint within the crate if a preview item is exposed by non-preview API. Use as an implementation detail is fine.
Like deprecated
, this attribute could admit additional metadata such as reason for unstability and planned stable release version.
Disadvantages
- Another thing to implement and maintain and learn. For full effect requires compiler and rustdoc support. However, the footprint is tiny and the
deprecated
machinery is already there. - This would be fairly useless for APIs that are being changed, not just amended with new items, although sometimes it's possible to publish a parallel preview version of an existing API.
Alternatives
-
Continue the status quo; strict semantic versioning only allows incompatible changes between major versions. Crate users have to use dev releases if they want to test new APIs.
-
Let crate authors rely on documentation, perhaps utilizing warning blocks. Downsides include lack of standard vocabulary and not being (easily) machine-readable or lintable. It's also fairly easy to forget to update documentation.
-
Have users put unstable things behind crate
feature
s.Upside is it's easy to have as fine-grained features as one wants. Downsides include lack of standard vocabulary, inability to use an inactive item even within the crate itself, lack of a "warn" level between disabled and enabled, and inability to include metadata (though features might permit this in the future).
-
Add a more general facility for creating and triggering custom lints that could be used for this purpose as well. A downside, again, is the lack of standard vocabulary as well as asymmetry with
deprecated
. This would also be a much larger change and would undoubtedly linger longer in development.
Unresolved questions
- Exhaustiveness: what to do with enum variants and struct fields? Could just disallow the use of the attribute with those, or only allow if the containing type is
non_exhaustive
.