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“
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.
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.