How to do new unstable api in stable crate

Hello

I'm maintaining a crate that already went 1.0. Now, I'm thinking about adding some more API surface to it, which is fine as far as semver goes. However, that includes the new API in the stability promise. I'd like to have it flexible for version or two before it is set to stone as well.

Is there a way to add a function or two into a crate and explicitly mark these as not-included in the stable promise? Something like rust's std does with feature flags?

I was thinking about a unstable-something-something crate feature that would force the user to enable it, but:

  • It doesn't seem very elegant
  • Some other crate in the dep graph can turn it on „by accident“

Does anyone have a better solution?

2 Likes

Some crates™ uses feature flags called nightly and I think if you state it in the docs, that things might break in the future if you rely on it (same as for the real nightly compiler) I think everybody will be okay with it.

1 Like

I think feature flag is ok. Other options:

  • Release it as 1.0-beta.1, these don't give stability guarantees.
  • Add #[deprecated(note = "experimental!")]
3 Likes

The deprecated thing might be the way to go I think. Or maybe in combination with the flag.

Rayon used to have an "unstable" feature, but we found that this created a problem between rayon and rayon-core, such that their versions needed to be more tightly coupled than they would otherwise. We ended up using a raw cfg that needs to be set in RUSTFLAGS, which is a high enough barrier that folks are less likely to use it, for better or worse. See #364 and #369.