Add some clarifying text to the transitioning steps.

[eminence]

I found myself confused by the current transition steps.

The first section talks about a preview phase and says "During the preview, there's an extra step you need to take to opt in [to Rust 2018]", and then describes the feature flag you need to enable. So I added that to my crate.

(I ran cargo fix, but that didn't change anything in my very bare-bones crate)

The next section is titled "Commit to the next edition". In my mind, I only want to see if my crate compiles with Rust 2018, I don't want to "commit" to use it. So I thought I could skip this step. But this is not correct -- I still need to modify my Cargo.toml file to enable Rust 2018 features.

So this PR tries to clarify these steps a bit. This text is written in my own personal style, so please review for style as well.

[Mark-Simulacrum]

This isn't quite true; the preview enables all of the relevant feature gates but does not permit use of a subset of 2018-only features. I'm not sure if the distinction is important to talk about here though.

[eminence]

Can you clarify this, for my own understanding? What subset of 2018-only features aren't permitted via this feature flag?

[Mark-Simulacrum]

The features on this list which are marked with minimum edition being 2018 are the ones that need the Cargo.toml switch flipped to use; the other features don't need that, the #![feature(rust_2018_preview)] or the more granular feature gates are sufficient for them.

[eminence]

That only applies to the unstable features, right? Here's what I'm seeing in my testing:

• A feature marked as both "Shipped" and minimum edition 2015 (like impl Trait) is immediately usable on the latest stable compiler (no feature flags needed, not Cargo.toml changes needed)
• A feature marked as "Unstable" and minimum edition 2015 (like in-band lifetimes) and be used with the rust_2018_preview, but no changes are needed to Cargo.toml.
• A feature marked as "Unstable" and minimum edition 2018 (like the module path change) requires both a feature flag (because it's unstable) and a change to Cargo.toml (because it's a 2018 feature).
• We don't currently have any of these yet, but if a feature was marked as "Shipped" and minimum edition 2018, then no feature flags would be needed, only edition=2018 in Cargo.toml.

So going back to your original comment: I still think my original text is correct ("you can't yet use Rust 2018 features until you enable them in your Cargo.toml file"). But you can use some new unstable features (like in-band lifetimes) that are being talked about in the edition transition guide, yet are actually Rust 2015 features).

Am I on the right track here?

[Mark-Simulacrum]

I think that's all correct: the distinction here is that inband lifetimes is a 2018 feature, but happens to also be usable on 2015. This distinction is what I think your text doesn't quite indicate, but I also don't think it is hugely important. Not sure though.

[eminence]

Thanks, I now understand. Do you think that we should spend some words on clarifying what features will only be available in the 2018 edition and features that will be able in 2015, but are going to be promoted/marketed as part of the 2018 edition? (If so, I would propose that be handled in another issue/PR)

[Centril]

You can always link to the list. :)

[eminence]

Great idea! I just pushed a new change that reads like this:

This will enable the unstable features listed in the feature status page. Note that some features require a miniumum of Rust 2018 and these features will require a Cargo.toml change to enable (described in the sections below). Also note that during the time the preview is available, we may continue to add/enable new features with this flag!

[steveklabnik]

Thanks!

[steveklabnik]

Thanks!

[Centril]

LGTM; Thanks!