Document that nightly features should be opt-in using a --cfg flag

[jyn514]

This was discussed (a long time ago now) in #95. I tried to make this a simple summary of that discussion and not editorialize too much. I did add a note on just running rustc --version, since that's nearly always broken.

I chose intrinsics::[black_box, catch_unwind} as the examples because a) they already have stable versions, so there's no temptation to copy them out of the docs, and b) intrinsics are perma-unstable and we won't need to update them.

[jyn514]

This PR was prompted by https://rust-lang.zulipchat.com/#narrow/channel/233931-t-compiler.2Fmajor-changes/topic/document.20RUSTC_BOOTSTRAP.20in.20the.20unstable.20.E2.80.A6.20compiler-team.23863/with/512532020. That discussion is long and most of it is not relevant; but maybe it's helpful context.

[jyn514]

oh - -Z allow-features is currently undocumented. I am in the process of documenting it in rust-lang/rust#139885; once that merges I'll link to it here and mention that feature detection should take it into account.

[taiki-e]

I personally prefer not to use the Cargo feature for this purpose (and use cfg instead), as it is easy to get into trouble if there is a crate enabling it somewhere in the dependency graph.

One of the real world examples where Cargo feature based approach was a problem was crossbeam-rs/crossbeam#435 where people encountered a problem and talked negatively about dependence on nightly-specific features (looking at some of the issues linked from there, it seems they thought it was automatically enabled), but it was actually opt-in feature and it was themselves or their other dependencies that actually opt-in-ed that feature.

See also rayon-rs/rayon#369, rayon-rs/rayon#364, tokio-rs/tokio#1774 (comment), https://github.com/dtolnay/proc-macro2#unstable-features, etc. for other discussions on using cfg instead of Cargo features for this or similar purpose.

[Mark-Simulacrum]

Suggested change

	- Add a `--cfg` flag which opts-in to the nightly features (optionally, with feature detection to verify the features are present in the current compiler version). This allows people to avoid opting-in if they do not want to be exposed to possible breakage.
	- Add a `--cfg` flag which opts-in to the nightly features (optionally, with a test compilation to provide better error messages from opt-in when feature is not supported). This allows people to avoid opting-in if they do not want to be exposed to possible breakage.

[Mark-Simulacrum]

Perhaps something like this? It's a stronger statement and less likely to be misread in a way that suggests avoiding the explicit opt-in.

[jyn514]

sure, i added something along those lines.