Determine how crates should expose 'unstable' APIs

[seanmonstar]

We want to mark crates as 1.0, and part of that requires all public dependencies to also be 1.0. It's possible an otherwise-stable crate would like to expose an API using a dependency that isn't stable yet. A common instance of this is futures. How should a crate expose this?

Some examples that I've seen:

• rayon requires RUSTFLAGS="--cfg rayon_unstable" to export the API that uses futures. As discussed there, this works closer to compiler unstable features, by requiring that the end user opt-in explicitly. A user cannot unknowingly depend on a crate using unstable features and think them stable.
• reqwest uses a Cargo feature, unstable. Additionally, all unstable APIs are put into reqwest::unstable, to try to remind anyone using it that those are not covered by semver.

[dtolnay]

Let's also consider how this applies to APIs that are unstable because they involve unstable Rust functionality—rather than a pre-1.0 public dependency.

I haven't thought much about pre-1.0 dependencies exposed by a 1.0 crate, but for APIs that depend on an unstable Rust feature I would like to recommend against using a blanket unstable feature. Serde does this wrong right now. Serde 1.0 has an unstable feature that enables impls for Box<CStr> and NonZero<T>. The problem with this is if somebody only needs one of these in their code, they don't want to be broken by nightly changes to the other one. It would be better to expose unstable-box-cstr and unstable-nonzero separately.

[sgrif]

Diesel also has an unstable feature which currently opts into functionality that requires nightly (currently I think the only case are a few impls which require specialization in order to be coherent).

I've been considering renaming the feature which maps to rust-nightly things to nightly, and having unstable mean "able to use optional dependencies of Diesel which are pre-1.0"

[kbknapp]

I've adopted to using a nightly feature which requires Rust Nightly, using unstable Nightly features. But I also have an unstable feature for things which may not make it into my stable API, but don't require Nightly Rust.

[KodrAus]

lazy_static is looking to stabilise using a nightly feature. The nightly for unstable Rust features vs unstable for unstable library features seems like a reasonable distinction to me.