RFC for #[stable(since)]
#3854
RFC for #[stable(since)]
#3854
Conversation
| - The entire `#[stable(feature)]`/`#[unstable(feature)]` functionality could be stabilized for 3rd party crates | ||
| - API stability could be stored outside of the source code, e.g. in a file similar to `rustdoc`'s JSON | ||
| - It could be shortened to `#[since("version")]` | ||
| - It could be expanded to `#[stable(added = "version", changed = "version", rust_version = "msrv")]` |
There was a problem hiding this comment.
🤔 Does "msrv" really belong here? If the rustc version is too old the crate would simply refuse to be compiled, regardless if the you the tagged API or not. Besides you can't bump the MSRV without publishing the package, so it can be inferred from the changed crate version already.
There was a problem hiding this comment.
I could see the argument that a person would maybe want to know "if I use this then I can't go back in rust version farther then X", but that's extremely rare. Usually people seem to have a particular (possibly locked) version of rust available, and then want to know what they can do while on that same version of rust.
ehuss
added
T-lang
|
|
||
| Should the `version` allow a placeholder value like `UNRELEASED`? | ||
|
|
||
| Is it clear enough that the version is the crate's own version and not the minimum requierd Rust version? |
There was a problem hiding this comment.
Are you thinking that a person would see a 1.0-series crate with "stable since 1.34" or something, and then think that it means that the crate provides an item as long as the rust version is 1.34? Because that's... Not How It Works for anything else in rust crates. A particular user could think that, but as soon as they ask almost anyone else I'm sure they'd be corrected.
There was a problem hiding this comment.
Note, however, that there are real world examples of crates providing their own APIs based on the Rust version (e.g., camino and fs-err wrap std APIs and use Rust version detection to support new additions without constantly bumping MSRV).
|
|
||
| Should crates reset the `version` when making semver-breaking changes to the item? | ||
|
|
||
| Should the `version` allow a placeholder value like `UNRELEASED`? |
There was a problem hiding this comment.
I think a rule like "you must put a string that can be a cargo crate version" is a simple enough rule, and however people want to get fancy with it is up to the ecosystem. For example, people could put the next minor version to be released, or put 0.0.0 as a placeholder, or whatever fits the project's tools and workflow.
There was a problem hiding this comment.
It is indeed, but if people are going to use 999.999.999 or 0.0.0-unreleased etc. as placeholders, we could as well provide some placeholder out of the box.
There was a problem hiding this comment.
Would love placeholder support as well as a teaching aid to use it (e.g. a clippy lint saying that the since is too new)
How does #[deprecated(since)] deal with any of this?
|
|
||
| Versions on re-exported items are not relevant for the crate re-exporting them, because it matters when the re-export has been added. | ||
|
|
||
| # Rationale and alternatives |
There was a problem hiding this comment.
There can be multiple ways something can be stable. Today, std also uses const_stable. I assume this should at least be acknowledged in case it can affect the design. Today they are separate attributes. Should we instead generalize stable to make it work for both? What impact may that have on this attribute?
|
|
||
| The entire `#[stable(feature)]`/`#[unstable(feature)]` functionality could be stabilized for 3rd party crates. | ||
|
|
||
| Tools like rust-analyzer or clippy could help users bump versions in `Cargo.toml` when their crate uses items from a newer version of a dependency than the minimum version specified in `Cargo.toml`. |
There was a problem hiding this comment.
I would love to have something like clippy::incompatible_msrv for dependencies. We'd have to tell the "compiler" (clippy in this case) the minimum version of every direct dependency (and maybe their pub dependencies)
|
|
||
| How to support items re-exported from other crates? Could `use` support overriding `#[stable(since)]`? | ||
|
|
||
| # Future possibilities |
There was a problem hiding this comment.
cargo update could tell people to run some new command, like cargo report news clap@before clap@after and see what is newly available.
Even better if we can get some form of "behavior change" and "remove attributes" (along with the stable deprecated) along with build-flow analysis and tailor those parts of the report specifically to your use of the library (plus the new stuff)
| - It could be shortened to `#[since("version")]` | ||
| - It could be expanded to `#[stable(added = "version", changed = "version", rust_version = "msrv")]` | ||
|
|
||
| # Prior art |
There was a problem hiding this comment.
Should we also talk about #[deprecated] as it serves a similar role.
|
Unsure what has been holding this up but would really love to have this! |
RFC for the issue rust-lang/rust#74182
Rendered